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

# Notifications

> Consumer Offer and Entitlement lifecycle notifications sent by the DVM™ to keep Resellers informed of key subscription events.

## Overview

The DVM™ sends notifications to your system whenever a Consumer Offer or Entitlement changes state. These notifications allow you to react in real time to subscription lifecycle events — provisioning outcomes, cancellations, activations, and product changes — and take the appropriate action for your consumers.

There are two categories of notification covered on this page:

<CardGroup cols={2}>
  <Card title="Consumer Offer Notifications" icon="box-open-full">
    Triggered when the overall status of a Consumer Offer changes — for example when all entitlements are created, or when a cancellation completes.
  </Card>

  <Card title="Entitlement Notifications" icon="ticket">
    Triggered when an individual Entitlement changes state — for example when a consumer activates their product, or when their access is terminated.
  </Card>
</CardGroup>

<Info>
  Billing-related notifications — including renewal charges, pro-rated charges, and refund outcomes — are covered separately on the [Billing & Charging Notifications](/billing-and-charging/notifications) page.
</Info>

***

## Consumer Offer notifications

A Consumer Offer is the top-level object that represents a consumer's subscription. The DVM™ sends a notification whenever the overall status of the Offer changes — whether provisioning succeeds, partially fails, or cancellation is scheduled or completed.

### Notification types

<CardGroup cols={2}>
  <Card title="Offer Created" icon="circle-check">
    All entitlements in the Offer were successfully created. The consumer now has access to all purchased services. `notificationReason: CONSUMER_OFFER_CREATED`
  </Card>

  <Card title="Offer Partially Created" icon="circle-half-stroke">
    At least one entitlement was created and at least one failed. The Reseller must review and decide whether to retry, notify the consumer, or cancel. `notificationReason: CONSUMER_OFFER_PARTIALLY_CREATED`
  </Card>

  <Card title="Cancel Pending" icon="clock">
    Cancellation has been scheduled. The Offer remains active but is marked with sub-status `PENDING_CANCELS`. `notificationReason: CONSUMER_OFFER_CANCEL_PENDING`
  </Card>

  <Card title="Offer canceled" icon="circle-xmark">
    All entitlements have been successfully terminated. The consumer no longer has access to any purchased services. `notificationReason: CONSUMER_OFFER_CANCELLED`
  </Card>

  <Card title="_Offer Partially Cancelled_" icon="circle-half-stroke">
    *At least one entitlement was terminated and at least one was not. The Reseller* must review which products are fully terminated and apply the appropriate access rules. `notificationReason: CONSUMER_OFFER_PARTIALLY_CANCELLED`
  </Card>
</CardGroup>

### Examples

<AccordionGroup>
  <Accordion title="Consumer Offer Created">
    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 safely assume the consumer now has access to all purchased services.

    ```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",
          "merchantAcccountKey": "BANGO_US",
          "productKey": "MUSIC",
          "source": {
            "channelType": "Website",
            "bundleId": "externalOfferReference",
            "country": "UK",
            "region": "Cambridgeshire",
            "brand": "ABC"
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Consumer Offer Partially Created">
    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",
          "merchantAcccountKey": "BANGO_US",
          "productKey": "MUSIC"
        },
        {
          "entitlementId": "a1d4f6b2-9c55-4e77-8a3b-2c4e1599f002",
          "sharedCustomerId": "8b61c84d-7e32-4a3b-9c22-1ac42f7d2f33",
          "status": "CREATE_FAILED",
          "subStatus": "",
          "merchantAcccountKey": "BANGO_US",
          "productKey": "VIDEO"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Consumer Offer Cancel Pending">
    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"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Consumer Offer canceled">
    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 safely assume the consumer no longer has access to any purchased services.

    ```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",
          "merchantAcccountKey": "BANGO_US",
          "productKey": "MUSIC",
          "source": {
            "channelType": "Website",
            "bundleId": "externalOfferReference",
            "country": "UK",
            "region": "Cambridgeshire",
            "brand": "ABC"
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Consumer Offer Partially Cancelled">
    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",
          "merchantAcccountKey": "BANGO_US",
          "productKey": "MUSIC"
        },
        {
          "entitlementId": "7b77319d-320c-475e-8f2f-a878b8f1828e",
          "sharedCustomerId": "245ce8a6-0ef3-4c38-804b-86dbe21d1d1d",
          "status": "CREATED",
          "subStatus": "PENDING_ACTIVATE",
          "merchantAcccountKey": "BANGO_US",
          "productKey": "VIDEO"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

### What to do with Consumer Offer notifications

| Notification | Suggested Reseller action |
| - | - |
| `CONSUMER_OFFER_CREATED` | Confirm to the consumer that their subscription is active and all products are accessible |
| `CONSUMER_OFFER_PARTIALLY_CREATED` | Review the failed entitlements and decide whether to retry provisioning, notify the consumer, or cancel the Offer |
| `CONSUMER_OFFER_CANCEL_PENDING` | Notify the consumer their subscription is scheduled to end and confirm the cancellation date |
| `CONSUMER_OFFER_CANCELLED` | Confirm to the consumer that their subscription has ended and all access has been removed |
| `CONSUMER_OFFER_PARTIALLY_CANCELLED` | Identify which products are terminated, apply appropriate access rules, and notify the consumer of their updated service state |
| `CONSUMER_OFFER_CREATE_FAILED` | |

***

## Entitlement notifications

An Entitlement represents an individual consumer's access to a specific product tier provisioned as part of a Consumer Offer. The DVM™ sends a notification whenever an Entitlement changes state — from activation through to termination and product changes.

### Notification types

<CardGroup cols={2}>
  <Card title="Activation Success" icon="circle-check">
    The consumer's entitlement has been activated and they now have active access to the product. `notificationReason: ACTIVATION_SUCCESS`
  </Card>

  <Card title="Termination Pending" icon="clock">
    The entitlement is pending termination at a future date. Access continues until the termination date is reached. `notificationReason: TERMINATION_PENDING`
  </Card>

  <Card title="Termination Success" icon="circle-xmark">
    The entitlement has ended. The consumer's access to the product has been removed. `notificationReason: TERMINATION_SUCCESS`
  </Card>

  <Card title="Product Update" icon="arrow-right-arrow-left">
    The product the consumer has access to has changed — for example following an upgrade, downgrade, or catalog change. The `productKey` is updated to the new value. `notificationReason: PRODUCT_UPDATE`
  </Card>

  <Card title="Metadata Update" icon="pen-to-square">
    Metadata on the entitlement has been successfully updated. `notificationReason: METADATA_UPDATE`
  </Card>
</CardGroup>

### Entitlement notification payload structure

All entitlement notifications follow the same structure. Fields may vary slightly depending on the event.

```json theme={null}
{
  "notificationReason": "ACTIVATION_SUCCESS",
  "entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
  "customerIdentifier": "123456789",
  "sharedCustomerId": "db2001b5-fde5-4654-9ecd-b3b04ba8f025",
  "bangoUserId": "6817257108240469082",
  "merchantAcccountKey": "BANGO_US",
  "productKey": "MUSIC",
  "status": "Active",
  "dateCreated": {},
  "dateActivated": {},
  "responseCode": "OK",
  "responseMessage": "Success",
  "parameters": null
}
```

### Examples

<AccordionGroup>
  <Accordion title="Activation Success">
    Sent when the consumer's entitlement has been successfully activated. The entitlement `status` is `Active`. Use this notification to confirm to the consumer that their product is ready to use.

    ```json theme={null}
    {
      "notificationReason": "ACTIVATION_SUCCESS",
      "entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
      "customerIdentifier": "123456789",
      "sharedCustomerId": "db2001b5-fde5-4654-9ecd-b3b04ba8f025",
      "bangoUserId": "6817257108240469082",
      "merchantAcccountKey": "BANGO_US",
      "productKey": "MUSIC",
      "status": "Active",
      "dateCreated": {},
      "dateActivated": {},
      "responseCode": "OK",
      "responseMessage": "Success",
      "parameters": null
    }
    ```
  </Accordion>

  <Accordion title="Termination Pending">
    Sent when the consumer's entitlement is scheduled for termination at a future date. The entitlement `status` is `Active-Ending` — the consumer still has access until the termination date. A `TERMINATION_SUCCESS` notification will follow when termination completes.

    ```json theme={null}
    {
      "notificationReason": "TERMINATION_PENDING",
      "entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
      "customerIdentifier": "123456789",
      "sharedCustomerId": "db2001b5-fde5-4654-9ecd-b3b04ba8f025",
      "bangoUserId": "6817257108240469082",
      "merchantAcccountKey": "BANGO_US",
      "productKey": "MUSIC",
      "status": "Active-Ending",
      "dateCreated": {},
      "dateActivated": {},
      "responseCode": "OK",
      "responseMessage": "Success",
      "parameters": null
    }
    ```
  </Accordion>

  <Accordion title="Termination Success">
    Sent when the consumer's entitlement has been successfully terminated. The entitlement `status` is `Cancelled` or `Revoked`. The consumer no longer has access to the product.

    ```json theme={null}
    {
      "notificationReason": "TERMINATION_SUCCESS",
      "entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
      "customerIdentifier": "123456789",
      "sharedCustomerId": "db2001b5-fde5-4654-9ecd-b3b04ba8f025",
      "bangoUserId": "6817257108240469082",
      "merchantAcccountKey": "BANGO_US",
      "productKey": "MUSIC",
      "status": "Cancelled",
      "dateCreated": {},
      "dateActivated": {},
      "responseCode": "OK",
      "responseMessage": "Success",
      "parameters": null
    }
    ```
  </Accordion>

  <Accordion title="Product Update">
    Sent when the product associated with the entitlement has changed — for example following an upgrade or downgrade. The `productKey` is updated to reflect the consumer's new product tier. Use this notification to update your records and surface the change to the consumer.

    ```json theme={null}
    {
      "notificationReason": "PRODUCT_UPDATE",
      "entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
      "customerIdentifier": "123456789",
      "sharedCustomerId": "db2001b5-fde5-4654-9ecd-b3b04ba8f025",
      "bangoUserId": "6817257108240469082",
      "merchantAcccountKey": "BANGO_US",
      "productKey": "MUSIC_PREMIUM",
      "status": "Active",
      "dateCreated": {},
      "dateActivated": {},
      "responseCode": "OK",
      "responseMessage": "Success",
      "parameters": null
    }
    ```
  </Accordion>

  <Accordion title="Metadata Update">
    Sent when metadata on the entitlement has been successfully updated. This notification signals that non-product, non-status attributes on the entitlement have changed — for example custom data, source information, or extension fields. Use this notification to keep your records in sync with the latest entitlement metadata.

    ```json theme={null}
    {
      "notificationReason": "METADATA_UPDATE",
      "entitlementId": "772ed60d-4a28-4a51-adfd-309e5949b6cf",
      "customerIdentifier": "123456789",
      "sharedCustomerId": "db2001b5-fde5-4654-9ecd-b3b04ba8f025",
      "bangoUserId": "6817257108240469082",
      "merchantAcccountKey": "BANGO_US",
      "productKey": "MUSIC",
      "status": "Active",
      "dateCreated": {},
      "dateActivated": {},
      "dateLastUpdated": "2026-06-09T10:00:00.000Z",
      "responseCode": "OK",
      "responseMessage": "Success",
      "parameters": null
    }
    ```
  </Accordion>
</AccordionGroup>

### What to do with Entitlement notifications

| Notification | Suggested Reseller action |
| - | - |
| `ACTIVATION_SUCCESS` | Confirm to the consumer that their product is active and ready to use |
| `TERMINATION_PENDING` | Notify the consumer their access will end on the scheduled date |
| `TERMINATION_SUCCESS` | Confirm to the consumer that their product access has been removed |
| `PRODUCT_UPDATE` | Update your records to reflect the new product tier and notify the consumer of the change |
| `METADATA_UPDATE` | Update your records to reflect the latest entitlement metadata |

***

## Key fields explained

<ResponseField name="notificationReason" type="string" required>
  Identifies the notification type. See the tables above for all possible values across Consumer Offer and Entitlement notifications.
</ResponseField>

<ResponseField name="consumerOffer.status" type="string">
  Present on Consumer Offer notifications. The overall status of the Consumer Offer. Key values: `FULLY_CREATED`, `PARTIALLY_CREATED`, `FULLY_CANCELED`, `PARTIALLY_CANCELED`.
</ResponseField>

<ResponseField name="consumerOffer.subStatus" type="string">
  Present on Consumer Offer notifications where a transitional state applies. For example `PENDING_CANCELS` when a cancellation has been scheduled but not yet completed.
</ResponseField>

<ResponseField name="consumerOffer.timeline" type="object">
  Contains key timestamps for the Consumer Offer lifecycle — including `createdTs`, `terminatedTs`, and `plannedCancellationTs` where applicable.
</ResponseField>

<ResponseField name="entitlements" type="array">
  Present on Consumer Offer notifications. An array of all entitlements associated with the Offer, each with its own `entitlementId`, `status`, `subStatus`, `productKey`, and `merchantAccountKey`. Check each entry individually when handling partial creation or partial cancellation notifications.
</ResponseField>

<ResponseField name="entitlementId" type="string">
  Present on Entitlement notifications. The unique identifier of the entitlement that changed state.
</ResponseField>

<ResponseField name="productKey" type="string">
  Present on Entitlement notifications. The product key associated with the entitlement. Updated to the new value on `PRODUCT_UPDATE` notifications.
</ResponseField>

<ResponseField name="status" type="string">
  Present on Entitlement notifications. The current status of the entitlement. Key values: `Active`, `Active-Ending`, `Cancelled`, `Revoked`.
</ResponseField>

<ResponseField name="consumer.communicationInformation" type="object">
  Present on Consumer Offer notifications. Contains `emailAddress` and `msisdn` for the consumer — useful for triggering downstream consumer communications.
</ResponseField>