Notifications

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:

Consumer Offer Notifications

Triggered when the overall status of a Consumer Offer changes — for example when all entitlements are created, or when a cancellation completes.

Entitlement Notifications

Triggered when an individual Entitlement changes state — for example when a consumer activates their product, or when their access is terminated.

Billing-related notifications — including renewal charges, pro-rated charges, and refund outcomes — are covered separately on the Billing & Charging Notifications page.

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

Offer Created

All entitlements in the Offer were successfully created. The consumer now has access to all purchased services. notificationReason: CONSUMER_OFFER_CREATED

Offer Partially Created

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

Cancel Pending

Cancellation has been scheduled. The Offer remains active but is marked with sub-status PENDING_CANCELS. notificationReason: CONSUMER_OFFER_CANCEL_PENDING

Offer canceled

All entitlements have been successfully terminated. The consumer no longer has access to any purchased services. notificationReason: CONSUMER_OFFER_CANCELLED

Offer Partially Cancelled

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

Examples

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.

{
  "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"
      }
    }
  ]
}

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.

{
  "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"
    }
  ]
}

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.

{
  "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"
    }
  ]
}

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.

{
  "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"
      }
    }
  ]
}

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.

{
  "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"
    }
  ]
}

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

Activation Success

The consumer’s entitlement has been activated and they now have active access to the product. notificationReason: ACTIVATION_SUCCESS

Termination Pending

The entitlement is pending termination at a future date. Access continues until the termination date is reached. notificationReason: TERMINATION_PENDING

Termination Success

The entitlement has ended. The consumer’s access to the product has been removed. notificationReason: TERMINATION_SUCCESS

Product Update

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

Metadata Update

Metadata on the entitlement has been successfully updated. notificationReason: METADATA_UPDATE

Entitlement notification payload structure

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

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

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.

{
  "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
}

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.

{
  "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
}

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.

{
  "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
}

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.

{
  "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
}

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.

{
  "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
}

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

string

required

Identifies the notification type. See the tables above for all possible values across Consumer Offer and Entitlement notifications.

string

Present on Consumer Offer notifications. The overall status of the Consumer Offer. Key values: FULLY_CREATED, PARTIALLY_CREATED, FULLY_CANCELED, PARTIALLY_CANCELED.

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.

object

Contains key timestamps for the Consumer Offer lifecycle — including createdTs, terminatedTs, and plannedCancellationTs where applicable.

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.

string

Present on Entitlement notifications. The unique identifier of the entitlement that changed state.

string

Present on Entitlement notifications. The product key associated with the entitlement. Updated to the new value on PRODUCT_UPDATE notifications.

string

Present on Entitlement notifications. The current status of the entitlement. Key values: Active, Active-Ending, Cancelled, Revoked.

object

Present on Consumer Offer notifications. Contains emailAddress and msisdn for the consumer — useful for triggering downstream consumer communications.

Welcome

Getting started

Partner management

Migrating to DVM

Offer management

Entitlement management

Billing & Charging

Correlation and reconciliation

Dashboard and reporting

Partner care

Notifications

Overview

Consumer Offer Notifications

Entitlement Notifications

Consumer Offer notifications

Notification types

Offer Created

Offer Partially Created

Cancel Pending

Offer canceled

Offer Partially Cancelled

Examples

What to do with Consumer Offer notifications

Entitlement notifications

Notification types

Activation Success

Termination Pending

Termination Success

Product Update

Metadata Update

Entitlement notification payload structure

Examples

What to do with Entitlement notifications

Key fields explained

​Overview

Consumer Offer Notifications

Entitlement Notifications

​Consumer Offer notifications

​Notification types

Offer Created

Offer Partially Created

Cancel Pending

Offer canceled

Offer Partially Cancelled

​Examples

​What to do with Consumer Offer notifications

​Entitlement notifications

​Notification types

Activation Success

Termination Pending

Termination Success

Product Update

Metadata Update

​Entitlement notification payload structure

​Examples

​What to do with Entitlement notifications

​Key fields explained

Overview

Consumer Offer notifications

Notification types

Examples

What to do with Consumer Offer notifications

Entitlement notifications

Notification types

Entitlement notification payload structure

Examples

What to do with Entitlement notifications

Key fields explained