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

# Merchant Entitlement Reports

> Receiving reports about your entitlements

Bango creates daily, weekly, and monthly reports grouped by reseller, 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 Merchant Interface API for merchants, 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 and Monthly | All active entitlements at reporting time |
| Change Report | Daily, Weekly and Monthly | All entitlements that changed status during the reporting period |
| Event Report | Daily, Weekly and Monthly | All entitlement events during the reporting period (one entitlement may appear several times) |
| Summary Report | Daily, Weekly and 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/{reseller}/{frequency}
```

Where:

* *customer* is your unique Amazon S3 bucket
* *reseller* is a reseller account key Bango store when the reseller cretes 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 |
| - | - | - |
| `MerchantEntitlementId` | String | Entitlement identifier created on the merchant system. |
| `BangoEntitlementId` | String | Entitlement identifier created on the Bango system. Each entitlement has a unique identifier. |
| `Status` | String | Entitlement status, one of `Active`, `Active-Ending`, `Suspended`, `Cancelled`, `Revoked`, `Pending` or `Failed` |
| `MerchantAccountKey` | | Merchant the entitlement is against. |
| `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 timestamp string | Date/Time (UTC) the entitlement was created on the Bango system (status Pending). |
| `ActivatedDate` | dd/MM/yyyy HH:mm:ss timestamp string or null | Date/Time (UTC) the entitlement was activated on the Bango system (status Active). If the entitlement is still in a pending state, this field will be `null`. |
| `SuspendedDate` | dd/MM/yyyy HH:mm:ss timestamp string or null | Date/Time (UTC) the entitlement was suspended on the Bango system (status Suspended). If the entitlement is still in an Active state, this field will be `null`. |
| `ExpiryDate` | dd/MM/yyyy HH:mm:ss timestamp string or null | If an Expiry Date is set on entitlement creation, it will be shown here. If no expiry date is set, the field will be `null`. |
| `LastUpdated` | dd/MM/yyyy HH:mm:ss timestamp string | Date/Time (UTC) the entitlement last changed state or records updated on the Bango system. |
| `EndDate` | dd/MM/yyyy HH:mm:ss timestamp 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. |

##### Example

```text theme={null}
MerchantEntitlementId,BangoEntitlementId,Status,MerchantAccountKey,ProductKey,DisplayName,CreatedDate,ActivatedDate,SuspendedDate,ExpiryDate,LastUpdated,EndDate
58e4-7966-4ff2-b1cc-9dd6d5e59702,f3508609-0a98-40c3-9851-e8821ddb449a,Active,BANGO,BangoMusic,BangoMusic Streaming,"22/01/2022 04:36:49","22/01/2022 04:36:52",,,"22/01/2022 04:36:52",
0640-5be7-4b2f-bd60-6c3b512cca35,c2ccab37-84ac-423b-ae68-6a7390221636,Pending,BANGO,BangoMusic,BangoMusic Streaming,"22/02/2022 14:12:35",,,,"22/02/2022 14:12:35",
```

Example CSV report files can be found [here](https://github.com/BangoProducts/Developer-Tools/tree/master/Resale/Merchant/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 identifier for the merchant service. |
| `Total Pending Entitlements` | Number | Total count of `Pending` entitlements since launch. |
| `New Pending Entitlements in Current Period` | Number | The count of created entitlements in the reporting period in a `Pending` state. |
| `Total Active Entitlements` | Number | Total count of `Active` or `Active-Ending` entitlements since launch. |
| `New Activations in Current Period` | Number | The count of entitlements that were activatied in the reporting period. |
| `Total Deactivations` | Number | Total count of `Cancelled` or `Revoked` entitlements since launch. |
| `New Deactivations in Current Period` | Number | The count of entitlements that were `Cancelled` or `Revoked` in the reporting period. |
| `Total Rejections` | Number | Total count of rejected entitlements since launch. |
| `Total Rejections in Current Period` | Number | The count of rejected entitlements in the reporting period. |
| `Total Failed Entitlements` | Number | Total count of `Failed` entitlements since launch. |
| `Failed in Current Period` | Number | The count of entitlements that were `Failed` in the reporting period. |

##### Example

```text theme={null}
ProductDescription,ProductKey,"Total Pending Entitlements","New Pending Entitlements in Current Period","Total Active Promotion Subscribers","New Activations in Current Period","Total Deactivations","New Deactivations in Current Period","Total Rejections","Total Rejections In Current Period","Total Failed Entitlements","Failed in Current Period","Total active + pending entitlements"
"BangoMusic Streaming",BangoMusic,0,0,77,0,43,,0,,3,0,77
"BangoMusic Premium",BangoMusicPremium,0,0,13312,124,443,,0,,4,0,13312
```

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