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

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:

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:

{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
`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

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.

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

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.

← Previous: Reporting Overview Next: Merchant Record Correlation Reports →

In this section: