Optimization Protection

Manage reporting groups

Report groups allow you to group entities of the same type, so a single report can have details of multiple entities. The following sections describe how to:

Create a reporting group
Retrieve all reporting groups
Retrieve a specific reporting group
Retrieve reporting groups by type
Update a reporting group
Deactivate and reactivate a reporting group

Create a reporting group

You can create a reporting group for multiple entities by sending a POST call to the /reporting-groups endpoint using the following fields.

Required fields for creating a reporting group
Field name	Description
`reportingGroupName`	The name of the reporting group.
`reportingGroupDescription`	The textual description of a reporting group.
`childEntityInfo`	The object that contains the list of child entity details.
childEntityInfo.`entityType`	The level of the merchant relationship as it relates to the acquiring account. Allowed values are PE, TD, FTI, BU, CO, RGPE, RGTD, RGFTI, RGBU, RGCO.
childEntityInfo.`entityIds`	The list of child entities for the reporting group.

Attention

A reporting group must contain entities with the same merchant end of the day (MEOD) to avoid reporting reconciliation issues.

HTTP Method: POSTEndpoint: /reporting-groupsScenario: Creating a reporting group for BU.

Json

{
    "reportingGroupName": "Example RG 1",
    "reportingGroupDescription": "Description for Example RG 1",
    "childEntityInfo": [
        {
            "entityType": "BU",
            "entityIds": [
                "1285401",
                "123456"
            ]
        }
    ]
}

Response:

Json

{
    "next": null,
    "reportingGroupList": [
        {
            "reportingGroupId": 2407101611283768,
            "reportingGroupName": "Example RG 1",
            "reportingGroupType": "RGBU",
            "reportingGroupDescription": "Description for Example RG 1",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "BU",
                    "entityIds": [
                        "1285401",
                        "123456"
                    ]
                }
            ]
        }
    ],
    "lastPage": true
}

Create a multi-level reporting group

You can create a multi-level reporting group that consists of multiple reporting groups and entities as its members by sending a POST call to the /reporting-groups endpoint.

HTTP Method: POSTEndpoint: /reporting-groupsScenario: Creating a multi-level reporting group for RGTDs.

Json

{
    "reportingGroupName": "Example RG 2",
    "reportingGroupDescription": "Description for Example RG 2",
    "childEntityInfo": [
        {
            "entityType": "RGBU",
            "entityIds": [
                "2405141152387311",
                "2405141153250961"
            ]
        }
    ]
}

Response:

Json

{
    "next": null,
    "reportingGroupList": [
        {
            "reportingGroupId": 2407101611283768,
            "reportingGroupName": "Example RG 2",
            "reportingGroupType": "RGBU",
            "reportingGroupDescription": "Description for Example RG 2",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "RGBU",
                    "entityIds": [
                        "2405141152387311",
                        "2405141153250961"
                    ]
                }
            ]
        }
    ],
    "lastPage": true
}

The following is an example of creating a multi-level reporting group having reporting groups and entities as it members.

HTTP Method: POSTEndpoint: /reporting-groupsScenario: Creating a multi-level reporting group for RGTDs and TDs.

Json

{
    "reportingGroupName": "Example RG 3",
    "reportingGroupDescription": "Description for Example RG 3",
    "childEntityInfo": [
        {
            "entityType": "RGTD",
            "entityIds": [
                "2407092248548502"
            ]
        },
        {
            "entityType": "TD",
            "entityIds": [
                "1285401"
            ]
        }
    ]
}

Response:

Json

{
    "next": null,
    "reportingGroupList": [
        {
            "reportingGroupId": 2407101611283766,
            "reportingGroupName": "Example RG 3",
            "reportingGroupType": "RGTD",
            "reportingGroupDescription": "Description of Example RG 3",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "RGTD",
                    "entityIds": [
                        "2407092248548502"
                    ]
                },
                {
                    "entityType": "TD",
                    "entityIds": [
                        "1285401"
                    ]
                }
            ]
        }
    ],
    "lastPage": true
}

Note

A reporting group can include entities of any type but all entities within a single group must be of the same type (PE, TD, FTI, BU, CO).

Create a heterogeneous reporting group

You can create a heterogeneous reporting group (RGH) for multiple entities by sending a POST call to the /reporting-groups endpoint using the following fields.

Required fields for creating a RGH
Field name	Description
`reportingGroupName`	The name of the reporting group.
`reportingGroupDescription`	The textual description of a reporting group.
`childEntityInfo`	The object that contains the list of child entity details.
childEntityInfo.`entityType`	The level of the merchant relationship as it relates to the acquiring account. Allowed values are PE, TD, FTI, BU, CO, RGPE, RGTD, RGFTI, RGBU, RGCO.
childEntityInfo.`entityIds`	The list of child entities for the reporting group.

HTTP Method: POSTEndpoint: /reporting-groupsScenario: Creating a heterogeneous reporting group for CO, BU, and TD.

Json

{
  "reportingGroupName": "RGH-test",
  "reportingGroupDescription": "Heterogenous reporting group",
  "reportingGroupType": "RGH",
  "childEntityInfo": [
    {
      "entityType": "CO",
      "entityIds": [
        "233235"
      ]
    },
    {
      "entityType": "BU",
      "entityIds": [
        "126952"
      ]
    },
    {
      "entityType": "TD",
      "entityIds": [
        "188934"
      ]
    }
  ]
}

Response:

Json

{
  "next": null,
  "reportingGroupList": [
    {
      "reportingGroupId": 2509151900464748,
      "reportingGroupName": "RGH-test",
      "reportingGroupType": "RGH",
      "reportingGroupDescription": "Heterogenous reporting group",
      "reportingGroupStatus": "active",
      "childEntityInfo": [
        {
          "entityType": "CO",
          "entityIds": [
            "233235"
          ]
        },
        {
          "entityType": "BU",
          "entityIds": [
            "126952"
          ]
        },
        {
          "entityType": "TD",
          "entityIds": [
            "188934"
          ]
        }
      ]
    }
  ],
  "lastPage": true
}

Create a multi-level heterogeneous reporting group

You can create a multi-level RGH by sending a POST call to the /reporting-groups endpoint.

HTTP Method: POSTEndpoint: /reporting-groupsScenario: Creating a multi-level heterogeneous reporting group for RGCO, RGH, and TD.

Json

{
  "reportingGroupName": "RGH-test",
  "reportingGroupDescription": "Heterogenous reporting group",
  "reportingGroupType": "RGH",
  "childEntityInfo": [
    {
      "entityType": "RGCO",
      "entityIds": [
        "2507252256449185"
      ]
    },
    {
      "entityType": "RGH",
      "entityIds": [
        "2509151900464748"
      ]
    },
    {
      "entityType": "TD",
      "entityIds": [
        "188935"
      ]
    }
  ]
}

Response:

Json

{
  "next": null,
  "reportingGroupList": [
    {
      "reportingGroupId": 2509151903396055,
      "reportingGroupName": "RGH-test",
      "reportingGroupType": "RGH",
      "reportingGroupDescription": "Heterogenous reporting group",
      "reportingGroupStatus": "active",
      "childEntityInfo": [
        {
          "entityType": "RGCO",
          "entityIds": [
            "2507252256449185"
          ]
        },
        {
          "entityType": "RGH",
          "entityIds": [
            "2509151900464748"
          ]
        },
        {
          "entityType": "TD",
          "entityIds": [
            "188935"
          ]
        }
      ]
    }
  ],
  "lastPage": true
}

Retrieve all reporting groups

You can retrieve the details of all existing reporting groups by sending a GET call to the /reporting-groups endpoint.

HTTP Method: GETEndpoint: /reporting-groupsScenario: Retrieve all existing reporting groups

Json

{
    "next": null,
    "reportingGroupList": [
        {
            "reportingGroupId": 2405281843563422,
            "reportingGroupName": "Test RG 1",
            "reportingGroupType": "RGCO",
            "reportingGroupDescription": "Description for Test RG 1",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "RGCO",
                    "entityIds": [
                        "2405281411418952"
                    ]
                }
            ]
        },
        {
            "reportingGroupId": 2406191250353360,
            "reportingGroupName": "Test RG 2",
            "reportingGroupType": "RGFTI",
            "reportingGroupDescription": "Description for Test RG 2",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "RGFTI",
                    "entityIds": [
                        "2406171451357316",
                        "2406172051519433"
                    ]
                }
            ]
        },
        {
            "reportingGroupId": 2407301953029026,
            "reportingGroupName": "Test RG 3",
            "reportingGroupType": "RGCO",
            "reportingGroupDescription": "Description for Test RG 3",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "CO",
                    "entityIds": [
                        "992177865173"
                    ]
                }
            ]
        },
        {
            "reportingGroupId": 2405281241024428,
            "reportingGroupName": "Test RG 4",
            "reportingGroupType": "RGPE",
            "reportingGroupDescription": "Description for Test RG 4",
            "reportingGroupStatus": "inactive",
            "childEntityInfo": [
                {
                    "entityType": "PE",
                    "entityIds": [
                        "999843710269"
                    ]
                }
            ]
        },
        {
            "reportingGroupId": 2405232310294687,
            "reportingGroupName": "Test RG 5",
            "reportingGroupType": "RGCO",
            "reportingGroupDescription": "Description for Test RG 5",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "CO",
                    "entityIds": [
                        "990196188729"
                    ]
                }
            ]
        },
        {
            "reportingGroupId": 2406111001337308,
            "reportingGroupName": "Test RG 6",
            "reportingGroupType": "RGPE",
            "reportingGroupDescription": "Description for Test RG 6",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "RGPE",
                    "entityIds": [
                        "2406111000362692"
                    ]
                }
            ]
        },
        {
            "reportingGroupId": 2407121706482726,
            "reportingGroupName": "RGBU",
            "reportingGroupType": "RGBU",
            "reportingGroupDescription": "Semi hetero Level 2 RGBU with BU and another RGBU as immediate child nodes",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "RGBU",
                    "entityIds": [
                        "2407080209297523"
                    ]
                }
            ]
        },

        {
            "reportingGroupId": 2407150952224403,
            "reportingGroupName": "Test RG 7",
            "reportingGroupType": "RGTD",
            "reportingGroupDescription": "Description for Test RG 7",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "TD",
                    "entityIds": [
                        "1001"
                    ]
                }
            ]
        }
    ],
    "lastPage": true
}

Retrieve a specific reporting group

You can retrieve the details of a specific reporting group by sending a GET call to the /reporting-groups endpoint using the query parameter groupId.

HTTP Method: GETEndpoint: /reporting-groups?groupId=2406280103065416Scenario: Retrieve the reporting group with reportingGroupId = 2406280103065416

Json

{
    "next": null,
    "reportingGroupList": [
        {
            "reportingGroupId": 2406280103065416,
            "reportingGroupName": "Test RG 1",
            "reportingGroupType": "RGCO",
            "reportingGroupDescription": "Description for Test RG 1",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "RGCO",
                    "entityIds": [
                        "2405281411418952"
                    ]
                }
            ]
        }
    ],
    "lastPage": true
}

Retrieve reporting groups by group type

You can retrieve the details of reporting groups by reporting group type by sending a GET call to the /reporting-groups endpoint using the query parameter groupType.

HTTP Method: GETEndpoint: /reporting-groups?groupType=RGCOScenario: Retrieve the reporting group with reporting-group-type = RGCO

Json

{
    "next": null,
    "reportingGroupList": [
        {
            "reportingGroupId": 2405281843563422,
            "reportingGroupName": "Test RG 1",
            "reportingGroupType": "RGCO",
            "reportingGroupDescription": "Description for Test RG 1",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "RGCO",
                    "entityIds": [
                        "2405281411418952"
                    ]
                }
            ]
        },
        {
            "reportingGroupId": 2405232310294687,
            "reportingGroupName": "Test RG 5",
            "reportingGroupType": "RGCO",
            "reportingGroupDescription": "Description for Test RG 5",
            "reportingGroupStatus": "active",
            "childEntityInfo": [
                {
                    "entityType": "CO",
                    "entityIds": [
                        "990196188729"
                    ]
                }
            ]
        }
    ],
    "lastPage": true
}

Modify a reporting group

You can update an existing reporting group at any time by sending a PATCH call to the /reporting-groups/{groupId} endpoint. The changes to a reporting group are immediately reflected in the associated report configurations.

Note

Keep in mind that if you are a legacy reporting client, your existing reporting groups will seamlessly transition to Commerce platform reporting and can be accessed through the Reporting API or Digital Reporting on Commerce Center.

Any modifications made to these reporting groups in the Commerce platform reporting system will only affect Commerce platform reports configured with those groups, without impacting your legacy reports.
After modifications are made to these reporting groups, any further changes to the legacy reporting groups will not be synchronized with the Commerce platform reporting groups.

The following are the required and updateable fields for a reporting group:

Required and updateable fields for a reporting group
Field name	Description	Updateable (Yes or No)	Required (R) or Optional (O)
`reportingGroupType`	The category of the reporting group. Allowed values are RGPE, RGTD, RGFTI, RGBU, RGCO.	No	R
`reportingGroupName`	The name of the reporting group.	Yes	O
`reportingGroupDescription`	The textual description of the reporting group.	Yes	O
`childEntityInfo`	The object that contains the list of child entity details.	Yes	O
childEntityInfo.`entityType`	The level of the merchant relationship as it relates to the acquiring account. Allowed values are PE, TD, FTI, BU, CO, RGPE, RGTD, RGFTI, RGBU, RGCO.	Yes	O
childEntityInfo.`entityIds`	The list of child entities for the reporting group.	Yes	O
`reportingGroupStatus`	Status of the reporting group	Yes	O

HTTP Method: PATCHEndpoint: /reporting-groups/2409042109467790Scenario: Updating the reportingGroupName and reportingGroupDescription, of a reporting group with reportingGroupId = 2409042109467790

Json

{
    "reportingGroupType": "RGPE",
    "reportingGroupStatus": "active",
    "reportingGroupName": "Test RG 7",
    "reportingGroupDescription": "New description for RG..."
}

Response:

Json

{
    "reportingGroupId": 2409042109467790,
    "reportingGroupType": "RGPE",
    "reportingGroupName": "Test RG 7",
    "reportingGroupDescription": "New description for RG..",
    "reportingGroupStatus": "active",
    "childEntityInfo": [
        {
            "entityType": "PE",
            "entityIds": [
                "991440459211"
            ]
        },
        {
            "entityType": "RGPE",
            "entityIds": [
                "2409042106034913"
            ]
        }
    ]
}

Attention

You cannot modify the child entities and activate/deactivate a reporting group with a single PATCH request. You must use separate PATCH requests to modify and activate/deactivate.

Deactivate and reactivate a reporting group

You can deactivate/reactivate a reporting group by sending a PATCH call to the /reporting-groups/{groupId} endpoint and updating the reportGroupStatus to inactive/active accordingly. Keep in mind that you must use separate PATCH requests to modify the child entities and deactivate/reactivate the reporting group.

HTTP Method: PATCHEndpoint: /reporting-groups/2409042109467790Scenario: Deactivating a reporting group with reportingGroupId = 2409042109467790 by updating the reportGroupStatus to inactive.

Json

{
    "reportingGroupType": "RGPE",
    "reportingGroupStatus": "inactive",
    "reportingGroupName": "New name for RG",
    "reportingGroupDescription": "New description for RG"
}

Response:

Json

{
    "reportingGroupId": 2409042109467790,
    "reportingGroupType": "RGPE",
    "reportingGroupName": "New name for RG",
    "reportingGroupDescription": "New description for RG",
    "reportingGroupStatus": "inactive",
    "childEntityInfo": [
        {
            "entityType": "PE",
            "entityIds": [
                "991440459211"
            ]
        },
        {
            "entityType": "RGPE",
            "entityIds": [
                "2409042106034913"
            ]
        }
    ]
}

Report types

Report configuration

Manage report configurations

Manage reporting groups

Create a reporting group

Create a multi-level reporting group

Create a heterogeneous reporting group

Create a multi-level heterogeneous reporting group

Retrieve all reporting groups

Retrieve a specific reporting group

Retrieve reporting groups by group type

Modify a reporting group

Deactivate and reactivate a reporting group

Related