Bango uses cookies to give you the best website experience. By using this website you agree to let Bango use cookies. More info

Bango Developer

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:

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:

{type}_V1_{frequency}_{date}.csv

Where:

type is one of:

ARfor the Active report
CRfor the Change report
ERfor the Event report
SRfor the Summary report

frequency is one of:

M for monthly
W for weekly
D for daily

date is one of:

For monthly reports: the reporting period expressed asYYYYMM, for example 202008 for August 2020
For weekly or daily reports: the start of the reporting period expressed as YYYYMMDD, for example 20200817 for August 17, 2020

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

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

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,<ResellerExtensionData><Key1>Value1</Key1><cancelReasonCategory>CUSTOMER_CANCELLED</cancelReasonCategory><cancelReasonCode>NOT_RENEWED</cancelReasonCode><cancelReasonDescription>Customer did not renew their entitlement</cancelReasonDescription></ResellerExtensionData>
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,<ResellerExtensionData>Key2>Value2</Key2></ResellerExtensionData>
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,<ResellerExtensionData><Key2>Value2</Key2></ResellerExtensionData>

Example CSV report files can be found here.

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

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.

← Previous: Reporting overview Next: Reseller Record Correlation Reports →

In this section: