Skip to main content

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: POST

Endpoint: /reporting-groups

Scenario: Creating a reporting group for entities.

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: POST

Endpoint: /reporting-groups

Scenario: 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: POST

Endpoint: /reporting-groups

Scenario: 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).

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: GET

Endpoint: /reporting-groups

Scenario: 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: GET

Endpoint: /reporting-groups?groupId=2406280103065416

Scenario: 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: GET

Endpoint: /reporting-groups?groupType=RGCO

Scenario: 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.

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: PATCH

Endpoint: /reporting-groups/2409042109467790

Scenario: 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: PATCH

Endpoint: /reporting-groups/2409042109467790

Scenario: 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"
            ]
        }
    ]
}