> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reseller entitlement reports v2

> Receiving reports about your entitlements

Bango creates daily, weekly, and monthly reports grouped by merchant, and stores them in your own dedicated Amazon S3 bucket. You can use these reports for reconciliation purposes.

Reports are published within 24 hours of the end of the reporting period.

### Access control

When you sign up to use the Bango Reseller API for resellers, Bango Support will supply you with:

* **Amazon S3 endpoint**: all your reports will be stored here
* **Access key**: your unique username for accessing the S3 endpoint
* **Secret key**: your unique password for accessing the S3 endpoint

### Report types

| Report | Frequency | Description |
| - | - | - |
| Active report | Daily, weekly, monthly | All active entitlements at reporting time |
| Change report | Daily, weekly, monthly | All entitlements that changed status during the reporting period |
| Event report | Daily, weekly, monthly | All entitlement events during the reporting period (one entitlement may appear several times) |
| Summary report | Daily, weekly, monthly | For each product, data about the entitlements in each state – totals, and changes during the reporting period |

All reports use UTC timestamps. Weeks start on Monday.

### Locations

The reports are stored at:

```text theme={null}
s3://{customer}/EntitlementReports/{merchant}/{frequency}
```

Where:

* *customer* is your unique Amazon S3 bucket
* *merchant* is a merchant account key, as used when creating an entitlement
* *frequency* is either `Daily`, `Weekly`, or `Monthly`

### Filenames

Filenames have the format:

```text theme={null}
{type}_V1_{frequency}_{date}.csv
```

Where:

* *type* is one of:
* *frequency* is one of:
* *date* is one of:

For example:

* The filename `AR_V1_W_20200810.csv` is the Active report for the week commencing August 10, 2020
* The filename `CR_V1_M_202009.csv` is the Change report for September 2020

### File formats

All report files are Windows-1252 encoded and contain [RFC 4180-compliant comma-separated values (CSV)](https://tools.ietf.org/html/rfc4180).

The Active report, Change report, and Event report all have the same CSV columns. The Summary report uses a different set of columns.

#### Active, Change and Event reports

For the **Active report, Change report, and Event report**, the file contains these columns:

| Column | Type | Description |
| - | - | - |
| `ResellerCustomerId` | String | Customer identifier |
| `BangoEntitlementId` | String | The globally unique entitlement ID |
| `Status` | `Active`, `Active-Ending`, `Suspended`, `Cancelled`, `Revoked`, `Pending`, or `Failed` | The current entitlement status |
| `MerchantAccountKey` | String | The merchant's unique identifier in the Bango Platform |
| `MerchantEntitlementId` | String | Entitlement identifier created on the merchant system |
| `ProductKey` | String | The identifier for the merchant service you want to activate for the user. Bango owns these identifiers and makes them available to you as necessary |
| `DisplayName` | String | A user-visible string representing the entitlement |
| `CreatedDate` | `dd/MM/yyyy HH:mm:ss` string | UTC datetime at which the entitlement was created in the Bango Platform (status `Pending`) |
| `ActivatedDate` | `dd/MM/yyyy HH:mm:ss` string or `null` | UTC datetime at which the entitlement was activated in the Bango Platform (status `Active`). `null` if the entitlement is still in a pending state |
| `SuspendedDate` | `dd/MM/yyyy HH:mm:ss` string or `null` | UTC datetime at which the entitlement was suspended in the Bango Platform (status `Suspended`). `null` if the entitlement is still in an Active state |
| `ExpiryDate` | `dd/MM/yyyy HH:mm:ss` string or `null` | If an Expiry Date is set on entitlement creation, it is shown here as a UTC datetime. If no expiry date is set, the field is `null` |
| `LastUpdated` | `dd/MM/yyyy HH:mm:ss` string | UTC datetime at which the entitlement last changed state or its record was updated in the Bango Platform |
| `EndDate` | `dd/MM/yyyy HH:mm:ss` string | UTC datetime at which the entitlement ended in the Bango Platform (status `Cancelled` or `Revoked`). If the entitlement status is `Active-Ending` the UTC datetime will be set in the future to show when the entitlement will be `Cancelled`. `null` if the entitlement is still in an Active state. |
| `ExtensionDataFormat` | String | Format of the ExtensionData column |
| `ExtensionData` | XML serialised to string | Any custom data associated with the entitlement |

##### Example

```text theme={null}
ResellerCustomerId,BangoEntitlementId,Status,MerchantAccountKey,MerchantEntitlementId,ProductKey,DisplayName,CreatedDate,ActivatedDate,SuspendedDate,ExpiryDate,LastUpdated,EndDate,ExtensionDataFormat,ExtensionData
8c1a4625-6941-4c59-a42a-2463d7e71676,e0a3b246-421f-47bf-9bfb-f5d410ce7ece,Revoked,BANGO,f95fc6b5-828c-46a1-8690-71206f7a141e,BangoMusic,Bango Music Streaming,25/10/2021 15:40:21,25/10/2021 15:42:49,,,01/02/2022 22:33:00,01/02/2022 22:33:00,XML,Value1CUSTOMER_CANCELLEDNOT_RENEWEDCustomer did not renew their entitlement
ff975d4d-cd7c-49f7-bfc8-0bf734c49e39,08e79e7a-f6dd-4bfc-bfb6-dcbba289ebf2,Active,BANGO,d7c25829-6935-459f-8405-fa29aa30cfa2,BangoMusic,Bango Music Streaming,28/01/2022 14:53:22,01/02/2022 21:45:12,,,01/02/2022 21:45:16,,XML,Key2>Value2
644de9cc-e3ec-468e-a7aa-e3e2ec39bc77,69786cf0-a9bd-44af-ad35-04fb7f082714,Pending,BANGO,0a27f69b-2577-4ff9-aac6-b2595f17836e,BangoMusic,Bango Music Streaming,01/02/2022 20:01:25,01/02/2022 20:09:34,,,01/02/2022 20:09:37,,XML,Value2
```

Example CSV report files can be found [here](https://github.com/BangoProducts/Developer-Tools/tree/master/Resale/Reseller/Reports).

#### Summary reports

For the **Summary report**, the file contains these columns:

| Column | Type | Description |
| - | - | - |
| `Product Description` | String | Human-readable description of the product key |
| `Product Key` | String | The unique identifier for the merchant service |
| `Total Pending Entitlements` | Number | Total number of `Pending` entitlements |
| `New Pending Entitlements in Current Period` | Number | The number of entitlements created during the reporting period in a `Pending` state |
| `Total Active Entitlements` | Number | Total number of `Active` or `Active-Ending` entitlements |
| `New Activations in Current Period` | Number | The number of entitlements activated during the reporting period |
| `Total Deactivations` | Number | Total number of `Cancelled` or `Revoked` entitlements |
| `New Deactivations in Current Period` | Number | The number of entitlements `Cancelled` or `Revoked` during the reporting period |
| `Total Rejections` | Number | Total number of rejected entitlements |
| `Total Rejections in Current Period` | Number | The number of entitlements rejected during the reporting period |
| `Total Failed Entitlements` | Number | Total number of `Failed` entitlements |
| `Failed in Current Period` | Number | The number of entitlements set to `Failed` during the reporting period |

##### Example

```text theme={null}
EntitlementRouteId,ProductFamily,ProductKey,Total Pending Entitlements,New Pending Entitlements in Current Period,Total Active Entitlements,New Activations in Current Period,Total Deactivations,Total Deactivations in Current Period,Total Rejections,Total Rejections in Current Period,Total Failed Entitlements,Failed in Current Period,A count of total Active + Total Pending Entitlements
56,BangoMusic Streaming,BangoMusic,511,1,437,0,714,0,0,0,8,0,1084
56,BangoMusic Premium,BangoMusicPremium,8561,0,5068,0,20725,19,0,0,17,0,13781
```

Example CSV report files can be found [here](https://github.com/BangoProducts/Developer-Tools/tree/master/Resale/Reseller/Reports).