openapi: 3.1.0
info:
  version: 1.5.0
  title: Reseller Notifications
  description: |
    # Overview
    Bango uses notifications to tell you about changes that have been made to `entitlements` and `consumer offers`. Please see the different schemas for more information on what can be sent for each notification type.
    
    Changes can be content provider or reseller initiated, and should be used to ensure your records are in sync with Bango and the content provider.

    During onboarding, Bango can configure a default notification url for all notifications. You can also provide a `notificationUrl` when creating an entitlement. If this has been set against the entitlement, it will override the default value for all notifications relating to this entitlement.

    Notifications can be secured with one of the following options:
    - X-api-key
    - Basic authentication
    - OAuth2

    # Change log
    **2025-05-12** | v.1.5.1
    - Schema titles added, overview improved, mistakes in enums fixed

    **2025-05-09** | v.1.5.0
    - Added new notification for `CONSUMER_OFFER_CREATED`
    - 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.
    - Notification examples added

    **2025-04-06** | v.1.4.1
    - Overview added

    **2025-03-07** | v.1.4.0
    - `ConsumerOffer` resource added containing the `consumerOfferId`
    - Default notification url option added

    **2024-08-08** | v.1.3.0
    - Added basic authentication and OAuth2 security options

    **2023-11-14** | v.1.2.0
    - Added x-api-key authentication
    
    **2022-05-18** | v.1.0.1
    - Added new notification reason `METADATA_UPDATE`
    - Added new notification reason `TERMINATION_PENDING`
    - Added new status `ACTIVE-ENDING`

    **2020-11-02** | v.1.0.0
    - Initial release

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'
            examples:  
              Consumer offer created:
                value:
                  notificationReason: CONSUMER_OFFER_CREATED
                  consumerOffer:
                    consumerOfferId: 50f45c44-ce66-41e1-8082-8cb1d0a4ae53
                    status: FULLY_CREATED
                    consumerOfferTimeline:
                      createdTs: 2025-04-29T13:46:55.228Z
                  consumer:
                    consumerIdentifier: "123456789"
                  entitlements:
                    - entitlementId: 772ed60d-4a28-4a51-adfd-309e5949b6cf
                      status: CREATED
                      subStatus: PENDING_ACTIVATE
                      merchantAcccountKey: BANGO_US
                      productKey: MUSIC
              Entitlement activated:
                value:
                  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: 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"
                  merchantAcccountKey: 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
      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/
      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:
        responseCode: 
          type: string
          description: Deprecated. Please ignore. This field will be removed from consumer offer notifications. 
        responseMessage:
          type: string
          description: Deprecated. Please ignore. This field will be removed from consumer offer notifications.
        notificationReason:
          type: string
          enum: [CONSUMER_OFFER_CREATED]
          description: | 
            The reason for sending a consumer offer notification
              - CONSUMER_OFFER_CREATED: A consumer offer, and associated entitlement(s), has been created
        consumerOffer:
          type: object 
          $ref: '#/components/schemas/ConsumerOffer'
        consumer:
          type: object 
          $ref: '#/components/schemas/Consumer'    
        entitlements:
          type: object
          $ref: '#/components/schemas/Entitlements' 
    ConsumerOfferTimeline:
        type: object
        properties:
          createdTs: 
            type: string
            format: date-time
            description: The date/time the consumer offer was created
    Consumer:
      type: object
      properties:
        consumerIdentifier: 
          type: string
          description: Unique, immutable user identifier. Referred to as `customerIdentifier` in entitlement notifications.     
    Entitlements:
      type: array
      items: 
        $ref: '#/components/schemas/EntitlementConsumerOfferView'
    EntitlementConsumerOfferView:
      type: object 
      properties:
        entitlementId:
          type: string
          description: Unique identifier representing a specific entitlement
        status:
          type: string
          enum: [REQUESTED, CREATED, ACTIVE, SUSPENDED, ENDED]
          description: The entitlement status
        subStatus:
          type: string
          enum: [PENDING_CREATE, PENDING_ACTIVATE, ENDING, CANCELLED, 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
    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 entitlment 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:
              - Pending: The entitlement has been initiated, but the user has not yet completed the activation process
              - Active: The entitlement has been successfully activated
              - Suspended: The entitlement has been suspended
              - Active-Ending: The entitlement is ending at the end of the current period
              - Cancelled: The entitlement has been cancelled
              - Revoked: The entitlement has been revoked
        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.92Z]
        dateActivated:
          type: string
          format: Date
          description: Timestamp provided by the content provider when the entitlement is activated
          examples: [2024-06-23T17:35:38.92Z]
        dateEnded:
          type: string
          format: date
          description: Timestamp for when the entitlement terminated
          examples: [0001-01-01T00:00:00Z]
        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:52Z]
        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:52Z]
        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:
          type: object
          $ref: '#/components/schemas/ExtensionData'
        extraInformation:
          type: object
          $ref: '#/components/schemas/ExtraInformation'
        financeData:
          type: object
          $ref: '#/components/schemas/FinanceData'
        consumerOffer:
          type: object
          $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: [example@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
    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
        status:
          type: string
          enum: [FULLY_CREATED]
          description: The status of the consumer offer
        consumerOfferTimeline:
          type: object
          $ref: '#/components/schemas/ConsumerOfferTimeline'

    Success:
      type: object
      required:
        - responseCode
        - responseMessage
      properties:
        responseCode:
          type: string
          enum: [OK]
        responseMessage:
          type: string
          examples: [Success]
      