> ## 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.
# Consumer Offer Notifications
> Consumer Offer notification reasons, provisioning and cancellation outcomes, payload examples, and reseller actions.
Bango DVM™ sends Consumer Offer notifications to report the outcome of provisioning and cancellation across all Entitlements in a Consumer Offer. Use these notifications to track the overall Consumer Offer lifecycle and identify where an individual Entitlement needs attention.
A Consumer Offer represents a consumer's subscription to an Offer. **Consumer Offer notifications report aggregate outcomes, not necessarily current Product access.** A successfully created Entitlement may still require activation.
## Notification reasons
| Notification reason | What happened | What to check |
| - | - | - |
| `CONSUMER_OFFER_CREATED` | All Entitlements were successfully created. | Creation completed; check individual Entitlement activation state before confirming Product access. |
| `CONSUMER_OFFER_PARTIALLY_CREATED` | At least one Entitlement was created and at least one failed. | Identify failed Entitlements and decide how to recover. |
| `CONSUMER_OFFER_CREATE_FAILED` | Entitlement creation failed, with no successfully created Entitlements. | Investigate the failure before attempting provisioning again. |
| `CONSUMER_OFFER_CANCEL_PENDING` | Cancellation has been scheduled. | The planned cancellation time; the Offer has not yet been fully terminated. |
| `CONSUMER_OFFER_CANCELLED` | All Entitlements reached the terminated outcome. | Treat the Consumer Offer as fully terminated. |
| `CONSUMER_OFFER_PARTIALLY_CANCELLED` | At least one Entitlement was terminated and at least one was not. | Inspect remaining Entitlements and resolve their access state. |
Consumer Offer status describes aggregate orchestration. Even an Offer that previously reached `FULLY_ACTIVE` can contain an Entitlement whose state changes later. Check individual Entitlements whenever current Product access matters.
## Provisioning outcomes
`CONSUMER_OFFER_CREATED`, `CONSUMER_OFFER_PARTIALLY_CREATED`, and `CONSUMER_OFFER_CREATE_FAILED` describe the outcome of Entitlement creation. They **do not** confirm that every Product is activated.
Consumer Offer creation can be asynchronous: `POST /consumerOffers` returns `202 Accepted`, while subsequent notifications report the completion or failure of provisioning. For partial failures, review the `entitlements` array to identify affected Products. For a failed creation outcome, investigate the cause before deciding whether to create a new Consumer Offer. If any Entitlements remain created in a particular failure or recovery scenario, handle their cleanup as appropriate rather than assuming that all resources were removed.
## Cancellation outcomes
`CONSUMER_OFFER_CANCEL_PENDING` indicates scheduled cancellation. Check `consumerOffer.timeline.plannedCancellationTs` when provided and continue to distinguish scheduled termination from completed termination. `CONSUMER_OFFER_CANCELLED` reports full completion; `CONSUMER_OFFER_PARTIALLY_CANCELLED` requires you to check which Entitlements have not terminated.
For individual access-level termination events, see [Entitlement notifications](/notifications/entitlements).
## Example notification payloads
The payloads below retain event-specific identifiers, timestamps, and Entitlement details from the original examples. Placeholder objects such as `{}` represent illustrative example values, not literal production timestamps.
Sent when all entitlements in the Offer are successfully created. The Offer status is `FULLY_CREATED` and all entitlements have status `CREATED`. The reseller can confirm provisioning has completed. Product activation may still be pending.
```json theme={null}
{
"notificationReason": "CONSUMER_OFFER_CREATED",
"consumerOffer": {
"consumerOfferId": "50f45c44-ce66-41e1-8082-8cb1d0a4ae53",
"offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
"status": "FULLY_CREATED",
"timeline": {
"createdTs": {}
}
},
"consumer": {
"consumerIdentifier": "123456789",
"communicationInformation": {
"emailAddress": "bob@company.com",
"msisdn": "+44123456789"
}
},
"entitlements": [
{
"entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
"sharedCustomerId": "245ce8a6-0ef3-4c38-804b-86dbe21d1d1d",
"status": "CREATED",
"subStatus": "PENDING_ACTIVATE",
"merchantAccountKey": "BANGO_US",
"productKey": "MUSIC",
"source": {
"channelType": "Website",
"bundleId": "externalOfferReference",
"country": "UK",
"region": "Cambridgeshire",
"brand": "ABC"
}
}
]
}
```
Sent when at least one entitlement was created successfully and at least one failed. The Offer status is `PARTIALLY_CREATED`. The Reseller must review the entitlements array to identify which products failed and decide whether to retry, notify the consumer, or cancel the Offer.
```json theme={null}
{
"notificationReason": "CONSUMER_OFFER_PARTIALLY_CREATED",
"consumerOffer": {
"consumerOfferId": "9fa1c2b4-7e89-4c3b-8a11-3b8f6ecf9a21",
"offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
"status": "PARTIALLY_CREATED",
"subStatus": "PENDING_ACTIVATES",
"timeline": {
"createdTs": {}
}
},
"consumer": {
"consumerIdentifier": "123456789",
"communicationInformation": {
"emailAddress": "bob@company.com",
"msisdn": "+44123456789"
}
},
"entitlements": [
{
"entitlementId": "e3c3c9f9-6a87-4c1c-9bbf-0e75a9a1d001",
"sharedCustomerId": "245ce8a6-0ef3-4c38-804b-86dbe21d1d1d",
"status": "CREATED",
"subStatus": "PENDING_ACTIVATE",
"merchantAccountKey": "BANGO_US",
"productKey": "MUSIC"
},
{
"entitlementId": "a1d4f6b2-9c55-4e77-8a3b-2c4e1599f002",
"sharedCustomerId": "8b61c84d-7e32-4a3b-9c22-1ac42f7d2f33",
"status": "CREATE_FAILED",
"subStatus": "",
"merchantAccountKey": "BANGO_US",
"productKey": "VIDEO"
}
]
}
```
Sent when a cancellation is initiated and the scheduling service successfully schedules it. The Offer status does not change but the sub-status moves to `PENDING_CANCELS`. The `plannedCancellationTs` indicates when the cancellation is due to complete.
```json theme={null}
{
"notificationReason": "CONSUMER_OFFER_CANCEL_PENDING",
"consumerOffer": {
"consumerOfferId": "55b63328-d55b-4e2c-958b-e376ea22bc7d",
"offerId": "810dbaa7-5848-4bc0-be4d-8ef83c320b3d",
"status": "FULLY_CREATED",
"subStatus": "PENDING_CANCELS",
"timeline": {
"plannedTs": "2026-05-04T11:25:22.456Z",
"plannedCancellationTs": "2026-06-04T11:25:22.455Z"
}
},
"consumer": {
"consumerIdentifier": "123456789",
"communicationInformation": {
"emailAddress": "bob@company.com",
"msisdn": "+44123456789"
}
},
"entitlements": [
{
"entitlementId": "8e848f25-6b7a-4ca2-a897-b1505f8afb34",
"merchantAccountKey": "NETFLIX_US",
"productKey": "7fa57b92-48de-4e53-b6bd-b0da2349e60a",
"sharedCustomerId": "3a4f84ac-e230-44a3-94cc-65ef457dcc4c",
"status": "CREATED",
"subStatus": "PENDING_ACTIVATE"
}
]
}
```
Sent when all entitlements in the Offer have been successfully terminated. The Offer status is `FULLY_CANCELED` and all entitlements have status `ENDED`. The reseller can treat the Consumer Offer as fully terminated.
```json theme={null}
{
"notificationReason": "CONSUMER_OFFER_CANCELLED",
"consumerOffer": {
"consumerOfferId": "50f45c44-ce66-41e1-8082-8cb1d0a4ae53",
"offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
"status": "FULLY_CANCELED",
"timeline": {
"createdTs": "2026-02-01T10:00:00.000Z",
"terminatedTs": "2026-02-02T10:00:00.000Z"
}
},
"consumer": {
"consumerIdentifier": "123456789",
"communicationInformation": {
"emailAddress": "bob@company.com",
"msisdn": "+44123456789"
}
},
"entitlements": [
{
"entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
"sharedCustomerId": "245ce8a6-0ef3-4c38-804b-86dbe21d1d1d",
"status": "ENDED",
"subStatus": "IMMEDIATE",
"merchantAccountKey": "BANGO_US",
"productKey": "MUSIC",
"source": {
"channelType": "Website",
"bundleId": "externalOfferReference",
"country": "UK",
"region": "Cambridgeshire",
"brand": "ABC"
}
}
]
}
```
Sent when at least one entitlement was terminated and at least one was not. The Offer status is `PARTIALLY_CANCELED`. The Reseller must review the entitlements array to determine which products are fully terminated and apply the appropriate product access and business rules.
```json theme={null}
{
"notificationReason": "CONSUMER_OFFER_PARTIALLY_CANCELLED",
"consumerOffer": {
"consumerOfferId": "50f45c44-ce66-41e1-8082-8cb1d0a4ae53",
"offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
"status": "PARTIALLY_CANCELED",
"subStatus": "PENDING_CANCEL",
"timeline": {
"createdTs": "2026-02-01T10:00:00.000Z",
"terminatedTs": "2026-02-02T10:00:00.000Z"
}
},
"consumer": {
"consumerIdentifier": "123456789",
"communicationInformation": {
"emailAddress": "bob@company.com",
"msisdn": "+44123456789"
}
},
"entitlements": [
{
"entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
"sharedCustomerId": "245ce8a6-0ef3-4c38-804b-86dbe21d1d1d",
"status": "ENDED",
"subStatus": "IMMEDIATE",
"merchantAccountKey": "BANGO_US",
"productKey": "MUSIC"
},
{
"entitlementId": "7b77319d-320c-475e-8f2f-a878b8f1828e",
"sharedCustomerId": "245ce8a6-0ef3-4c38-804b-86dbe21d1d1d",
"status": "CREATED",
"subStatus": "PENDING_ACTIVATE",
"merchantAccountKey": "BANGO_US",
"productKey": "VIDEO"
}
]
}
```
Sent when a Consumer Offer could not be created, for example because a Content Provider rejected the request to create an entitlement. `POST /consumerOffers` returns `202 Accepted` and creation continues asynchronously, so this notification is how you find out that creation did not complete, without relying on a successful creation notification.
```json theme={null}
{
"notificationReason": "CONSUMER_OFFER_CREATE_FAILED",
"consumerOffer": {
"consumerOfferId": "642f629e-780b-4103-9975-99a6d187cd5c",
"offerId": "13a152bb-29c6-4c01-b819-3ba41024f911",
"status": "CREATES_FAILED",
"timeline": {
"createdTs": null,
"createsFailedTs": "2026-08-26T09:39:36.755Z"
}
},
"consumer": {
"consumerIdentifier": "Testtest0010"
},
"entitlements": [
{
"entitlementId": "983bcf1b-6b33-42a0-9f64-b95fa2323d05",
"status": "CREATE_FAILED",
"merchantAccountKey": "NOBOBO_SUBS_MERCHANT",
"productKey": "Bango_Gamepass",
"merchantProductKey": "Bango_Gamepass",
"sharedCustomerId": "1d710b74-95b0-4294-bea6-4b5edc418464"
}
]
}
```
## Recommended reseller actions
| Notification | Suggested action |
| - | - |
| `CONSUMER_OFFER_CREATED` | Confirm that provisioning succeeded. Check activation status before telling the consumer each Product is ready to use. |
| `CONSUMER_OFFER_PARTIALLY_CREATED` | Review each failed Entitlement; determine whether to retry, inform the consumer, or cancel the Consumer Offer. |
| `CONSUMER_OFFER_CREATE_FAILED` | Investigate the failure before retrying or creating a replacement Consumer Offer. Assess whether any resources require cleanup. |
| `CONSUMER_OFFER_CANCEL_PENDING` | Record the planned cancellation and inform the consumer of the scheduled end date where appropriate. |
| `CONSUMER_OFFER_CANCELLED` | Record completed termination and confirm that the Consumer Offer has ended. |
| `CONSUMER_OFFER_PARTIALLY_CANCELLED` | Review the `entitlements` array, resolve any remaining Entitlement access, and inform the consumer of the correct status. |
## Key fields
Identifies the Consumer Offer notification, using one of the exact reason values listed above.
Unique identifier of the Consumer Offer affected by the notification.
Aggregate lifecycle status. Examples in these payloads include `FULLY_CREATED`, `PARTIALLY_CREATED`, `CREATES_FAILED`, `FULLY_CANCELED`, and `PARTIALLY_CANCELED`. This is not a substitute for an Entitlement's access status.
Transitional information when present, such as `PENDING_CANCELS` for scheduled cancellation. Use the actual value returned.
Relevant timestamps, which vary by event, including `createdTs`, `createsFailedTs`, `plannedTs`, `plannedCancellationTs`, and `terminatedTs`.
Identifies the consumer associated with the Consumer Offer.
Consumer contact information where present, such as `emailAddress` and `msisdn`. Do not assume this object is present in every notification.
Entitlements associated with the Consumer Offer. Check individual `entitlementId`, `status`, `subStatus`, `productKey`, and `merchantAccountKey` fields, where present, especially for partial outcomes.
Preserve returned API field names and enum values exactly. The examples include different shapes depending on the notification reason.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.