# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# 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

- Create a heterogeneous reporting group

- Retrieve all reporting groups

- Retrieve a specific reporting group

- Retrieve reporting groups by type

- Modify a reporting group - Temporarily disabled

- Deactivate and reactivate a reporting group - Temporarily disabled

## 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. | 

> 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 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:** `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
}
```

> 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, RGH. | 
| childEntityInfo.entityIds | The list of child entities for the reporting group. | 

**HTTP Method:** `POST
 `**Endpoint: **`/reporting-groups
 `**Scenario:** Creating a heterogeneous reporting group for CO, BU, TD, and PE.

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

**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"
          ]
        },
        {
          "entityType": "PE",
          "entityIds": [
            "991440459211"
          ]
        }
      ]
    }
  ],
  "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:** `POST
 `**Endpoint: **`/reporting-groups
 `**Scenario:** 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:** `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.

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

> 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"
            ]
        }
    ]
}
```

## Related

[Report types](/docs/commerce/optimization-protection/capabilities/reporting/report-types)

[Report configuration](/docs/commerce/optimization-protection/capabilities/reporting/report-configurations/scheduled-adhoc)

[Manage report configurations](/docs/commerce/optimization-protection/capabilities/reporting/how-to/manage-report-configurations)