openapi: 3.1.0
info:
  version: 1.10.0
  title: Reseller Notifications
  description: "# Overview\nBango uses notifications to tell you about changes that\
    \ have occured on `consumer offers` or `entitlements`.\nBango can also send notifications\
    \ for updates relating to the lifecycle and billing of consumer offers.\t\nPlease\
    \ see the different schemas below for more information on what can be sent for\
    \ each notification type.\n\nChanges can be content provider or reseller initiated,\
    \ and should be used to ensure your records are in sync with Bango and the content\
    \ provider.\n\nDuring onboarding, Bango can configure a default notification url\
    \ for all notifications. You can also provide a `notificationUrl`\nwhen creating\
    \ an entitlement. If this has been set against the entitlement, it will override\
    \ the default value for all notifications\nrelating to this entitlement.\n\nNotifications\
    \ can be secured with one of the following options:\n- X-api-key\n- Basic authentication\n\
    - OAuth2\n\n# Change log\n**2026-03-14** | v.1.10.0\n- Added consumer offer notification:\n\
    \    - `CONSUMER_OFFER_CANCEL_PENDING`\n\n**2026-02-09** | v.1.9.0\n- Added Consumer\
    \ Offer notifications:\n    - `Consumer Offer cancelled`\n    - `Consumer Offer\
    \ partially canceled`\n\n **2025-07-24** | v.1.8.0\n- Added billing-plan lifecycle\
    \ notifications:\n    - `UPCOMING_PHASE_CHANGE`\n    - `UPCOMING_RENEWAL`\n  \
    \  - `RENEWAL_SUCCEEDED`\n    - `RENEWAL_FAILED`\n\n**2025-07-16** | v.1.7.0\n\
    - `CONSUMER_OFFER_CREATED` notification has been enhanced to align more closely\
    \ with the consumer offer API. The following fields have therefore been added\
    \ and will be included in the notification if available:\n    - consumerOffer.offerId\n\
    \    - consumer.consumerIdentifier\n    - consumer.communicationInfo.emailAddress\
    \ (optional)\n    - consumer.communicationInfo.msisdn (optional)\n    - entitlement.sharedCustomerId\n\
    \    - entitlement.source.* (optional)\n\n**2025-07-04** | v.1.6.1\n- Clarity\
    \ on OAuth2 support added.\n\n**2025-06-10** | v.1.6.0\n- Removal of `responseCode`\
    \ and `responseMessage` from `CONSUMER_OFFER_CREATED` notification\n- `consumerOfferTimeline`\
    \ renamed to `timeline` in the `CONSUMER_OFFER_CREATED` notification to align\
    \ the notification content with the consumer offer API\n\n**2025-05-12** | v.1.5.1\n\
    - Schema titles added, overview improved, mistakes in enums fixed\n\n**2025-05-09**\
    \ | v.1.5.0\n- Added new notification for `CONSUMER_OFFER_CREATED`\n- Please note\
    \ that while `responseCode` and `responseMessage` are currently returned in the\
    \ consumer offer notification, this is an error and they will be removed as they\
    \ are not used.\n- Notification examples added\n\n**2025-04-06** | v.1.4.1\n-\
    \ Overview added\n\n**2025-03-07** | v.1.4.0\n- `ConsumerOffer` resource added\
    \ containing the `consumerOfferId`\n- Default notification url option added\n\n\
    **2024-08-08** | v.1.3.0\n- Added basic authentication and OAuth2 security options\n\
    \n**2023-11-14** | v.1.2.0\n- Added x-api-key authentication\n\n**2022-05-18**\
    \ | v.1.0.1\n- Added new notification reason `METADATA_UPDATE`\n- Added new notification\
    \ reason `TERMINATION_PENDING`\n- Added new status `ACTIVE-ENDING`\n\n**2020-11-02**\
    \ | v.1.0.0\n- Initial release\n"
security:
- XApiKey: []
- BasicAuth: []
- OAuth2: []
paths:
  /notificationUrl:
    post:
      tags:
      - Notifications
      summary: From Bango
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/Entitlement'
              - $ref: '#/components/schemas/ConsumerOfferNotification'
              - $ref: '#/components/schemas/BillingPlanNotification'
            examples:
              Consumer offer created:
                value:
                  notificationReason: CONSUMER_OFFER_CREATED
                  consumerOffer:
                    consumerOfferId: 50f45c44-ce66-41e1-8082-8cb1d0a4ae53
                    offerId: ce124847-08c4-4e0e-b917-9d5ef1240a69
                    status: FULLY_CREATED
                    timeline:
                      createdTs: '2025-04-29T13:46:55.228Z'
                  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
              Consumer offer canceled:
                value:
                  notificationReason: CONSUMER_OFFER_CANCELED
                  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
              Consumer offer partially canceled:
                value:
                  notificationReason: CONSUMER_OFFER_PARTIALLY_CANCELED
                  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
                    source:
                      channelType: Website
                      bundleId: externalOfferReference
                      country: UK
                      region: Cambridgeshire
                      brand: ABC
                  - entitlementId: 7b77319d-320c-475e-8f2f-a878b8f1828e
                    sharedCustomerId: 245ce8a6-0ef3-4c38-804b-86dbe21d1d1d
                    status: CREATED
                    subStatus: PENDING_ACTIVATE
                    merchantAccountKey: BANGO_US
                    productKey: VIDEO
                    source:
                      channelType: Website
                      bundleId: externalOfferReference
                      country: UK
                      region: Cambridgeshire
                      brand: ABC
              Entitlement activated:
                value:
                  notificationReason: ACTIVATION_SUCCESS
                  entitlementId: 772ed60d-4a28-4a51-adfd-309e5949b6cf
                  customerIdentifier: '123456789'
                  sharedCustomerId: db2001b5-fde5-4654-9ecd-b3b04ba8f025
                  bangoUserId: '6817257108240469082'
                  merchantAccountKey: BANGO_US
                  productKey: MUSIC
                  status: Active
                  dateCreated: '2025-05-09T16:24:38.996Z'
                  dateActivated: '2025-05-09T16:24:37.672Z'
                  responseCode: OK
                  responseMessage: Success
                  parameters: null
              Entitlement ended:
                value:
                  notificationReason: TERMINATION_SUCCESS
                  entitlementId: 772ed60d-4a28-4a51-adfd-309e5949b6cf
                  customerIdentifier: '123456789'
                  sharedCustomerId: db2001b5-fde5-4654-9ecd-b3b04ba8f025
                  bangoUserId: '6817257108240469082'
                  merchantAccountKey: BANGO_US
                  productKey: MUSIC
                  status: Revoked
                  dateCreated: '2025-05-09T16:24:38.996Z'
                  dateActivated: '2025-05-09T16:24:37.672Z'
                  dateLastUpdated: '2025-05-09T16:29:57.404Z'
                  dateEnded: '2027-08-09T16:30:54.141Z'
                  responseCode: OK
                  responseMessage: Success
                  parameters: null
              Upcoming phase change:
                value:
                  notificationReason: UPCOMING_PHASE_CHANGE
                  consumerIdentifier: bob@reseller.com
                  billingPlan:
                    billingPlanId: a783c985-d3bd-4725-9b8e-a81152bb690x
                    offer:
                      offerId: re124847-08c4-4e0e-b917-9d5ef1240a69
                      offerName: Music Bundle - 6 months free
                      consumerOfferId: 95bade98-3687-45b5-88b3-75d7b4283927
                  upcomingPhase:
                    sequence: 1
                    duration: EVERGREEN
                    startTs: '2025-07-01T12:34:41.834Z'
                  charge:
                    status: UPCOMING_CHARGE
                    phaseSequence: 1
                    currency: USD
                    amount: 1399
                    assetScale: 2
                    displayAmount: 13.99
                    chargeTs: '2025-07-01T12:34:41.834Z'
              Upcoming renewal:
                value:
                  notificationReason: UPCOMING_RENEWAL
                  consumerIdentifier: bob@reseller.com
                  billingPlan:
                    billingPlanId: a783c985-d3bd-4725-9b8e-a81152bb690x
                    offer:
                      offerId: re124847-08c4-4e0e-b917-9d5ef1240a69
                      offerName: Music Bundle - 6 months free
                      consumerOfferId: 95bade98-3687-45b5-88b3-75d7b4283927
                  charge:
                    status: UPCOMING_CHARGE
                    phaseSequence: 1
                    currency: USD
                    amount: 1399
                    assetScale: 2
                    displayAmount: 13.99
                    chargeTs: '2025-07-01T12:34:41.834Z'
              Renewal succeeded:
                value:
                  notificationReason: RENEWAL_SUCCEEDED
                  consumerIdentifier: bob@reseller.com
                  billingPlan:
                    billingPlanId: a783c985-d3bd-4725-9b8e-a81152bb690x
                    offer:
                      offerId: re124847-08c4-4e0e-b917-9d5ef1240a69
                      offerName: Music Bundle - 6 months free
                      consumerOfferId: 95bade98-3687-45b5-88b3-75d7b4283927
                  charge:
                    status: PAID
                    phaseSequence: 1
                    currency: USD
                    amount: 1399
                    assetScale: 2
                    displayAmount: 13.99
                    chargeTs: '2025-07-01T12:34:41.834Z'
              Renewal failed:
                value:
                  notificationReason: RENEWAL_FAILED
                  consumerIdentifier: bob@reseller.com
                  failureCode: USER_INSUFFICIENT_CREDIT
                  billingPlan:
                    billingPlanId: a783c985-d3bd-4725-9b8e-a81152bb690x
                    offer:
                      offerId: re124847-08c4-4e0e-b917-9d5ef1240a69
                      offerName: Music Bundle - 6 months free
                      consumerOfferId: 95bade98-3687-45b5-88b3-75d7b4283927
                  charge:
                    status: FAILED
                    phaseSequence: 1
                    currency: USD
                    amount: 1399
                    assetScale: 2
                    displayAmount: 13.99
                    chargeTs: '2025-07-01T12:34:41.834Z'
              Consumer offer cancel pending:
                value:
                  notificationReason: CONSUMER_OFFER_CANCEL_PENDING
                  consumerOffer:
                    consumerOfferId: 50f45c44-ce66-41e1-8082-8cb1d0a4ae53
                    offerId: ce124847-08c4-4e0e-b917-9d5ef1240a69
                    status: FULLY_ACTIVE
                    subStatus: PENDING_CANCEL
                    timeline:
                      createdTs: '2026-02-01T10:00:00.000Z'
                      plannedExpiryTs: '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
                  - entitlementId: 7b77319d-320c-475e-8f2f-a878b8f1828e
                    sharedCustomerId: 245ce8a6-0ef3-4c38-804b-86dbe21d1d1d
                    status: CREATED
                    subStatus: PENDING_ACTIVATE
                    merchantAccountKey: BANGO_US
                    productKey: VIDEO
                    source:
                      channelType: Website
                      bundleId: externalOfferReference
                      country: UK
                      region: Cambridgeshire
                      brand: ABC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Success'
components:
  securitySchemes:
    XApiKey:
      type: apiKey
      in: header
      name: x-api-key
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      description: 'Bango uses https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/.

        Please note that when requesting a token, we only support the option to send
        the client secret in the request body

        '
      flows:
        clientCredentials:
          tokenUrl: https://oauth.merchant.com/token
          scopes:
            any: grants Bango access to the merchant system based on merchant defined
              rules
  schemas:
    ConsumerOfferNotification:
      title: Consumer Offer Notification Schema
      type: object
      properties:
        notificationReason:
          type: string
          enum:
          - CONSUMER_OFFER_CANCELED
          - CONSUMER_OFFER_CREATED
          - CONSUMER_OFFER_PARTIALLY_CANCELED
          - CONSUMER_OFFER_CANCEL_PENDING
          description: "The reason for sending a consumer offer notification\n  -\
            \ CONSUMER_OFFER_CREATED: A consumer offer, and associated entitlement(s),\
            \ has been created\n  - CONSUMER_OFFER_CANCELED: A consumer offer, and\
            \ all associated entitlement(s), has been canceled\n  - CONSUMER_OFFER_PARTIALLY_CANCELED:\
            \ A consumer offer has been partially canceled (one or more entitlements\
            \ canceled while others remain)\n  - CONSUMER_OFFER_CANCEL_PENDING: A\
            \ consumer offer remains active but has been scheduled for cancellation\
            \ at a future date"
        consumerOffer:
          $ref: '#/components/schemas/ConsumerOffer'
        consumer:
          $ref: '#/components/schemas/Consumer'
        entitlements:
          $ref: '#/components/schemas/Entitlements'
    Timeline:
      type: object
      properties:
        createdTs:
          type: string
          format: date-time
          description: The date/time the consumer offer was created
        terminatedTs:
          type: string
          format: date-time
          description: The date/time the consumer offer was terminated
        plannedExpiryTs:
          type: string
          format: date-time
          description: The date/time the consumer offer is scheduled to expire
    Consumer:
      type: object
      properties:
        consumerIdentifier:
          type: string
          description: Unique, immutable user identifier. Referred to as `customerIdentifier`
            in entitlement notifications.
        communicationInformation:
          $ref: '#/components/schemas/CommunicationInformation'
    Entitlements:
      type: array
      items:
        $ref: '#/components/schemas/EntitlementConsumerOfferView'
    EntitlementConsumerOfferView:
      type: object
      properties:
        entitlementId:
          type: string
          description: Unique identifier representing a specific entitlement
        sharedCustomerId:
          type: string
          format: uuid
          description: Unique identifier for this consumer on this route
        status:
          type: string
          enum:
          - REQUESTED
          - CREATED
          - ACTIVE
          - SUSPENDED
          - ENDED
          description: The entitlement status
        subStatus:
          type: string
          enum:
          - CANCELLED
          - ENDING
          - IMMEDIATE
          - PENDING_ACTIVATE
          - PENDING_CREATE
          - REVOKED
        merchantAccountKey:
          type: string
          description: Unique identifier for the content provider
        productKey:
          type: string
          description: Unique identifier for the product/tier/offer on this route
        source:
          $ref: '#/components/schemas/Source'
    ConsumerOffer:
      type: object
      required:
      - consumerOfferId
      properties:
        consumerOfferId:
          type: string
          format: uuid
          description: Unique identifier of the consumer offer. If the entitlement
            is part of a consumer offer, the consumerOfferId will be included in the
            notification
        offerId:
          type: string
          format: uuid
          description: Unique identifier of the offer in the offer catalog
        status:
          type: string
          enum:
          - FULLY_ACTIVE
          - FULLY_CREATED
          - FULLY_CANCELED
          - PARTIALLY_CANCELED
          description: The status of the consumer offer
        timeline:
          $ref: '#/components/schemas/Timeline'
        subStatus:
          type: string
          enum:
          - PENDING_CANCEL
          description: Additional status detail for the consumer offer
    BillingPlanNotification:
      title: Billing Plan Notification Schema
      type: object
      required:
      - notificationReason
      - consumerIdentifier
      - billingPlan
      properties:
        notificationReason:
          type: string
          enum:
          - UPCOMING_PHASE_CHANGE
          - UPCOMING_RENEWAL
          - RENEWAL_SUCCEEDED
          - RENEWAL_FAILED
          description: "The reason for sending a billing plan notification:\n  - UPCOMING_PHASE_CHANGE:\
            \ A phase change is scheduled to begin in the future\n  - UPCOMING_RENEWAL:\
            \ A renewal charge is scheduled to be attempted in the future\n  - RENEWAL_SUCCEEDED:\
            \ A renewal charge has succeeded\n  - RENEWAL_FAILED: A renewal charge\
            \ has failed\n"
        consumerIdentifier:
          type: string
          description: Reseller-defined identifier for the consumer (e.g. email or
            internal user id).
        failureCode:
          type: string
          nullable: true
          enum:
          - OPERATION_NOT_SUPPORTED
          - DENIED
          - USER_INVALID
          - USER_BARRED
          - USER_SUSPENDED
          - USER_NOT_ENABLED
          - USER_INSUFFICIENT_CREDIT
          - USER_SPEND_LIMIT_EXCEEDED
          - ALREADY_IN_PROGRESS
          - PAYMENT_UNKNOWN
          description: 'Present for `RENEWAL_FAILED`. High-level reason for the payment
            failure.

            '
        billingPlan:
          $ref: '#/components/schemas/BillingPlan'
        upcomingPhase:
          $ref: '#/components/schemas/UpcomingPhase'
        charge:
          $ref: '#/components/schemas/Charge'
    BillingPlan:
      type: object
      required:
      - billingPlanId
      - offer
      properties:
        billingPlanId:
          type: string
          format: uuid
          description: Unique identifier for the billing plan.
        offer:
          $ref: '#/components/schemas/OfferSummary'
    OfferSummary:
      type: object
      required:
      - offerId
      - offerName
      - consumerOfferId
      properties:
        offerId:
          type: string
          format: uuid
          description: Unique identifier for the offer in the offer catalog.
        offerName:
          type: string
          description: Display name for the offer.
        consumerOfferId:
          type: string
          format: uuid
          description: Unique identifier for the consumer offer instance.
    UpcomingPhase:
      type: object
      nullable: true
      description: Present for `UPCOMING_PHASE_CHANGE`.
      required:
      - sequence
      - duration
      - startTs
      properties:
        sequence:
          type: integer
          description: The upcoming phase sequence number.
        duration:
          type: string
          description: The phase duration descriptor.
          examples:
          - EVERGREEN
        startTs:
          type: string
          format: date-time
          description: Date/time the upcoming phase will begin.
    Charge:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - UPCOMING_CHARGE
          - PAID
          - FAILED
          description: "The charge status:\n  - UPCOMING_CHARGE: A charge is expected\
            \ in the future\n  - PAID: The charge succeeded\n  - FAILED: The charge\
            \ failed\n"
        phaseSequence:
          type: integer
          nullable: true
          description: Phase sequence the charge relates to (if applicable).
        currency:
          type: string
          nullable: true
          description: ISO 4217 currency code (e.g. USD, GBP).
        amount:
          type: integer
          nullable: true
          description: Integer amount in minor units (see assetScale).
        assetScale:
          type: integer
          nullable: true
          description: Number of decimal places for amount.
        displayAmount:
          type: number
          nullable: true
          format: double
          description: Human-readable amount (amount / 10^assetScale).
        chargeTs:
          type: string
          nullable: true
          format: date-time
          description: Date/time the charge is/was due (and used as charge timeline
            anchor).
    Entitlement:
      title: Entitlement Notification Schema
      type: object
      required:
      - notificationReason
      - entitlementId
      - customerIdentifier
      - merchantAccountKey
      - productKey
      - status
      properties:
        notificationReason:
          type: string
          enum:
          - ACTIVATION_SUCCESS
          - PRODUCT_UPDATE
          - METADATA_UPDATE
          - SUSPENSION_SUCCESS
          - RESUMPTION_SUCCESS
          - TERMINATION_PENDING
          - TERMINATION_SUCCESS
          - ACCOUNT_UNLINKED
          - ACCOUNT_LINKED
          description: '- ACTIVATION_SUCCESS: The entitlement has been activated

            - PRODUCT_UPDATE: The productKey on the entitlement has been updated

            - METADATA_UPDATE: Metadata on the entitlement has been updated

            - SUSPENSION_SUCCESS: The entitlement has been SUSPENDED

            - RESUMPTION_SUCCESS: The entitlement has been resumed. The entitlement''s
            status will return to what it was prior to it being suspended

            - TERMINATION_PENDING: The entitlement has been marked for termination
            at a future date

            - TERMINATION_SUCCESS: The entitlement has been terminated

            - ACCOUNT_UNLINKED: The entitlement is no longer linked to the merchant''s
            user account. The entitlement may be inaccessible by the customer and
            recovery action is required

            - ACCOUNT_LINKED: The entitlement has been linked to a merchant''s user
            account

            '
        entitlementId:
          type: string
          description: Unique identifier representing a specific entitlement
        customerIdentifier:
          type: string
          description: Unique, immutable user identifier
          examples:
          - '123456789'
        sharedCustomerId:
          type: string
          format: uuid
          description: Bango generated id shared between reseller and merchant for
            this customer (contact support for setup)
          examples:
          - db2001b5-fde5-4654-9ecd-b3b04ba8f025
        merchantAccountKey:
          type: string
          description: Unique identifier for the content provider
          examples:
          - BANGO_US
        productKey:
          type: string
          description: Unique identifier for the product/tier/offer on this route
          examples:
          - MUSIC
        status:
          type: string
          examples:
          - Active
          enum:
          - Pending
          - Active
          - Suspended
          - Active-Ending
          - Cancelled
          - Revoked
          description: "The entitlement status. Possible values are:\n  - Pending:\
            \ The entitlement has been initiated, but the user has not yet completed\
            \ the activation process\n  - Active: The entitlement has been successfully\
            \ activated\n  - Suspended: The entitlement has been suspended\n  - Active-Ending:\
            \ The entitlement is ending at the end of the current period\n  - Cancelled:\
            \ The entitlement has been cancelled\n  - Revoked: The entitlement has\
            \ been revoked\n"
        notificationUrl:
          type: string
          format: url
          description: The endpoint where Bango will send all notifications regarding
            this entitlement
          examples:
          - https://notifications.bango.com
        offerKey:
          type: string
          description: Entitlement offer identifier
          examples:
          - BUNDLE
        externalEntitlementId:
          type: string
          description: Unique identifier for the entitlement provided by the reseller.
            If the previous attempt to create an entitlement failed, this value can
            be reused.
          examples:
          - 124130d2-2cbc-45a1-ab9b-dfa8b67a2e63
        entitlementDisplayName:
          type: string
          description: Entitlement display name used in reports.
          examples:
          - 30 day free trial for Bango Music
        dateCreated:
          type: string
          format: date
          description: Timestamp for the creation of the entitlement
          examples:
          - '2024-06-22T17:35:38.920Z'
        dateActivated:
          type: string
          format: date
          description: Timestamp provided by the content provider when the entitlement
            is activated
          examples:
          - '2024-06-23T17:35:38.920Z'
        dateEnded:
          type: string
          format: date
          description: Timestamp for when the entitlement terminated
          examples:
          - '0001-01-01T00:00:00.000Z'
        dateSuspended:
          type: string
          format: date
          description: Timestamp for when the entitlement was suspended
          examples:
          - null
        dateResumed:
          type: string
          format: date
          description: Timestamp for when the entitlement was last resumed
          examples:
          - null
        dateExpiry:
          type: string
          format: date
          description: If set, Bango will schedule a termination request to the content
            provider on this date. Date format must be ISO 8601
          examples:
          - '2024-12-05T07:46:52.000Z'
        dateAutoSuspend:
          type: string
          format: date
          description: If set, Bango will schedule a suspension request to the content
            provider on this date. Date format must be ISO 8601
          examples:
          - '2024-09-05T07:46:52.000Z'
        responseCode:
          type: string
          examples:
          - OK
          description: Deprecated. Please ignore. This field is not used.
        responseMessage:
          type: string
          examples:
          - Success
          description: Deprecated. Please ignore. This field is not used.
        activationCode:
          type: string
          description: Code or token used for the entitlement activation
          examples:
          - null
        parameters:
          type: object
          properties:
            Action:
              type: string
              description: The action the reseller should take next
              enum:
              - NAVIGATE_TO_URL
            Url:
              type: string
              description: The activation url provided by the content provider. Redirect
                the customer to this link to continue the activation process.
              examples:
              - https://activation-link.bango.com
        extensionDataList:
          $ref: '#/components/schemas/ExtensionData'
        extraInformation:
          $ref: '#/components/schemas/ExtraInformation'
        financeData:
          $ref: '#/components/schemas/FinanceData'
        consumerOffer:
          $ref: '#/components/schemas/ConsumerOffer'
    ExtensionData:
      type: object
      description: Custom key value pairs
      properties:
        customField1:
          type: string
          examples:
          - value1
        customField2:
          type: string
          examples:
          - value2
    ExtraInformation:
      type: object
      properties:
        communicationInformation:
          $ref: '#/components/schemas/CommunicationInformation'
        clientDevice:
          $ref: '#/components/schemas/ClientDevice'
        source:
          $ref: '#/components/schemas/Source'
    CommunicationInformation:
      type: object
      properties:
        msisdn:
          type: string
          examples:
          - '441234567890'
        emailAddress:
          type: string
          examples:
          - bob@bango.com
    ClientDevice:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - STB
          - MOBILE
          - DESKTOP
          - TABLET
          description: The type of device. This field is mandatory if clientDevice
            is being provided
          examples:
          - STB
        id:
          type: string
          description: The unique id of the device
          examples:
          - bc449c9e-406f-4399-a3ff-8671a27ac410
        typeId:
          type: string
          description: The common id for the type of device
          examples:
          - P49AJFND8NFN23NANGAJG
        modelName:
          type: string
          description: The model name of the device
          examples:
          - STB Model X7
        modelNumber:
          type: string
          description: The model number of the device
          examples:
          - IAH45IAOF/5
        serialNumber:
          type: string
          description: The serial number of the device
          examples:
          - JHFJHA43JNFA9393GFD
        osType:
          type: string
          description: The operating system of the device
          examples:
          - Linux
        osVersion:
          type: string
          description: The version of the operating system of the device
          examples:
          - 10.3.8
        macAddress:
          type: string
          description: The MAC address of the device
          examples:
          - 4A-0F-99-F2-D3-DD
        browser:
          type: string
          description: The browser being used
          examples:
          - Chrome
    Source:
      type: object
      properties:
        channelType:
          type: string
          enum:
          - Retail
          - SMS
          - App
          - Website
          - Email
          - Call Centre
          - Mobile
          - Set Top Box
          - Other
          description: The channel the customer used to get the offer
          examples:
          - Retail
        campaignRef:
          type: string
          description: The reference of the campaign that attracted the customer
          examples:
          - SUMMER_PROMO
        referrer:
          type: string
          description: The origin of the customer's request
          examples:
          - SEARCH_ENGINE
        bundleId:
          type: string
          description: Identifies the bundle the entitlement is part of
          examples:
          - BundleABC123
        country:
          type: string
          description: The customer's country
          examples:
          - United Kingdom
        region:
          type: string
          description: The customer's regional area or code
          examples:
          - CB1 3ED
        brand:
          type: string
          description: The brand
          examples:
          - BrandA
    FinanceData:
      type: object
      required:
      - source
      - type
      - timestamp
      properties:
        source:
          type: string
          description: The source of the finance event
          enum:
          - Merchant
        type:
          type: string
          description: The type of finance event
          enum:
          - order
          - return
          - renew
        timestamp:
          type: string
          format: date
          description: UTC ISO 8601
        retailCurrency:
          type: string
          description: ISO 3
        retailPrice:
          type: number
          format: double
          description: As per standard price element, including tax
        retailPriceTax:
          type: number
          format: double
          description: As per standard price element, tax included in the retailPrice
        offerPrice:
          type: number
          format: double
          description: As per standard price element, including tax
        offerPriceTax:
          type: number
          format: double
          description: As per standard price element, tax included in the offerPrice
        notes:
          type: string
          description: Free text field, max 255 characters
    Success:
      type: object
      required:
      - responseCode
      - responseMessage
      properties:
        responseCode:
          type: string
          enum:
          - OK
        responseMessage:
          type: string
          examples:
          - Success
