openapi: 3.1.0
info:
  version: 1.4.0
  title: Merchant-api-client

servers:
  - url: https://music.resale.api.bango.net 
    description: This is the content provider's base url. The Bango Music demo url is shown.
security:
  - basic: []

paths:
  /v1/entitlement:
    post:
      summary: Create entitlement
      description: |
        Request that is sent to the merchant to create a new Entitlement and
        return Activation URL and related parameters to be sent to the user.
        Expected responses as defined below.
      operationId: create
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Request unique identifier. This id should be used for idempotency.
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      requestBody:
        description: The entitlement JSON sent to merchant to create a subscription
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementCreate'
            examples:  
              BaseRequest:
                value:
                  requestId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                  bangoUserId: 1549053185
                  sharedCustomerId: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e
                  resellerId: XYZ_RESELLER
                  productId: BangoMusic
                  offerId: FREE_FOR_6_MONTHS
                  customerId: 123456789
                  status: PENDING
              ExtendedRequest:
                value:
                  requestId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                  bangoUserId: 1549053185
                  sharedCustomerId: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e
                  resellerId: XYZ_RESELLER
                  productId: BangoMusic
                  offerId: FREE_FOR_6_MONTHS
                  customerId: 123456789
                  status: PENDING
                  merchantExtensionData:
                    customField1: value1
                    customField2: value2
                  extraInformation:
                    clientDevice:
                      type: STB
                      id: bc449c9e-406f-4399-a3ff-8671a27ac410
                      typeId: P49AJFND8NFN23NANGAJG
                      modelName: STB Model X7
                      modelNumber: IAH45IAOF/5
                      serialNumber: JHFJHA43JNFA9393GFD
                      osType: Linux
                      osVersion: 10.3.8
                      macAddress: 4A-0F-99-F2-D3-DD
                      browser: Chrome
                    communicationInformation: 
                      msisdn: "441234567890"
                      emailAddress: example@bango.com
                    source: 
                      channelType: Retail,
                      campaignRef: SUMMER_PROMO
                      referrer: SEARCH_ENGINE
                      bundleId: BundleABC123
                      country: United Kingdom
                      region: CB1 3ED
                      brand: BrandA
                  merchantBangoExtensionData: 
                    customField1: value1
                    customField2: value2
      responses:
        '200':
          description: Entitlement created and activated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementCreate200Response'
        '201':
          description: Entitlement created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementCreate201Response'
        '202':
          description: An action is required to be performed by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementCreate202Response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '409':
          description: Already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlreadyExists'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteralServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
      
    patch:
      summary: Update entitlement
      description: |
        Request to update an entitlement's data e.g. `productKey`
      operationId: update
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Request unique identifier. This id should be used for idempotency.
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      responses:
        '200':
          description: Entitlement updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
        '202':
          description: Request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestAccepted'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '409':
          description: Operation invalid for the current state of the entitlement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidState'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteralServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdate'
        description: The entitlement JSON you want to update
        required: true
  '/v1/entitlement/activationInfo/{merchantEntitlementId}':
    post:
      summary: Request activation info
      description: |
        This endpoint is used to request activation information for entitlements in a `PENDING` status. This endpoint is used for new requests as well as refresh requests for expired activation information.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Request unique identifier. This id should be used for idempotency.
          schema:
            type: string
            format: uuid
        - name: merchantEntitlementId
          in: path
          description: Unique identifier used on activation.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      responses:
        '200':
          description: Activation information provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivationInfoResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteralServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivationInfo'
        description: The activation information request JSON.       

  '/v1/entitlement/suspend/{merchantEntitlementId}':
    post:
      summary: Suspend entitlement
      description: Send a request to the merchant to suspend an entitlement.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Request unique identifier. This id should be used for idempotency.
          schema:
            type: string
            format: uuid
        - name: merchantEntitlementId
          in: path
          description: Unique identifier used on activation.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdate'
      responses:
        '200':
          description: Entitlement suspended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementSuspendResponse'
        '202':
          description: Suspend request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestAccepted'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteralServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
  '/v1/entitlement/resume/{merchantEntitlementId}':
    post:
      summary: Resume entitlement
      description: Send a request to the merchant to resume an entitlement.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Request unique identifier. This id should be used for idempotency.
          schema:
            type: string
            format: uuid
        - name: merchantEntitlementId
          in: path
          description: Unique identifier used on activation.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      requestBody:
        description: The entitlement revoke JSON.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdate'
      responses:
        '200':
          description: Entitlement suspended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementSuspendResponse'
        '202':
          description: Suspend request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestAccepted'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteralServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'      
        
  '/v1/entitlement/terminate/{merchantEntitlementId}':
    post:
      summary: Terminate entitlement
      description: >
        Request sent to merchant to end an entitlement. The body contains a flag
        called "IMMEDIATE" that marks if the request is for a HARD / SOFT
        termination.
          - Immediate = true is an instruction for the merchant to terminate the entitlement effective immediately.
          - Immediate = false is an instruction for the merchant to terminate the entitlement at the end of it's current billing lifecycle.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Request unique identifier. This id should be used for idempotency.
          schema:
            type: string
            format: uuid
        - name: merchantEntitlementId
          in: path
          description: Unique identifier used on activation.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      responses:
        '200':
          description: Entitlement terminated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementTerminateResponse'
        '202':
          description: Request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestAccepted'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteralServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementTerminate'
        description: The entitlement revoke JSON.
  '/v1/notifications':
    post:
      tags:
        - Entitlement
      summary: Top up notifications
      description: The Bango DVM can be configured to send top up notifications to the merchant when top ups are created and/or when they are activated 
      parameters:
        - name: X-RequestIdentifier
          in: header
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopUpsNotifications'
            examples:  
              Top up created:
                value:
                  notificationType: "TOP_UP_CREATED"
                  merchantEntitlementId: "cde150ac-9e4f-45f9-a352-8682228aefb1"
                  entitlementId: "6d644dff-9706-4fe4-adc4-78c312904e7e"
                  topUps:
                    - topUpId: "c64e64b7-8822-44d9-8345-46c3f32999a2"
                      productKey: "1DAY_MUSIC"
                      createdTs: "2024-10-11T15:57:08.603Z"
              Top up activated:
                value:
                  notificationType: "TOP_UP_ACTIVATED"
                  merchantEntitlementId: "cde150ac-9e4f-45f9-a352-8682228aefb1"
                  entitlementId: "6d644dff-9706-4fe4-adc4-78c312904e7e"
                  topUp:
                    topUpId: "c64e64b7-8822-44d9-8345-46c3f32999a2"
                    productKey: "1DAY_MUSIC"
                    createdTs: "2024-10-11T15:57:08.603Z"
                    startTs: "2024-10-11T16:09:43.571Z"
                    endTs: "2024-10-12T16:09:43.570Z"
      responses:
        '200':
          description: Top up notification accepted (no response body required)

components:
  securitySchemes:
    basic:
      type: http
      description: Basic authentication
      scheme: basic
    OAuth2:
      type: oauth2
      description: Bango uses OAuth2 with the clientCredentials grant flow
      flows:
        clientCredentials:
          tokenUrl: 'https://oauth.merchant.com/token'
          scopes:
            any: grants Bango access to the merchant system based on merchant defined rules
  schemas:
    TopUpsNotifications:
      type: object
      properties:
        notificationType:
          type: string
        merchantEntitlementId:
          type: string
        entitlementId:
          type: string
          format: uuid
        topUp:
          $ref: '#/components/schemas/TopUp'
        topUps:
          $ref: '#/components/schemas/TopUps'
    TopUp:
      type: object
      properties:
        topUpId:
          type: string
          format: uuid
        productKey:
          type: string
        createdTs:
          type: string
          format: datetime
        startTs:
          type: string
          format: datetime
        endTs:
          type: string
          format: datetime
    TopUps:
      type: object
      properties:
        topUpId:
          type: string
          format: uuid
        productKey: 
          type: string
        createdTs: 
          type: string
          format: datetime
        startTs: 
          type: string
          format: datetime
        endTs: 
          type: string
          format: datetime
    EntitlementUpdate:
      type: object
      required:
        - merchantEntitlementId
        - bangoUserId
        - productId
        - resellerId
      properties:
        merchantEntitlementId:
          type: string
          description: Unique identifier used on activation
          examples: [6e37a4b5-8cb9-465b-88a9-ad5eb02596be]
          format: uuid
        bangoUserId:
          type: string
          description: 'Unique user identifier, as identified by Bango'
          examples: [1549053185]
        sharedCustomerId:
          type: string
          description: Bango generated id shared between reseller and merchant for this customer (contact support for setup)
          examples: [414b3019-0c28-4d14-9c5f-6217b8bd1e3e]
          format: uuid
        productId:
          type: string
          description: 'Entitlement product unique identifier. For example, "30_DAYS_MUSIC".'
          examples: [30_DAYS_MUSIC]
        resellerId:
          type: string
          description: Unique reseller identifier
          examples: [XYZ_RESELLER]
        entitlementBenefits:
          type: string
          description: |
            ENUM parameter to instruct the type of benefits
            action needed as part of the update request only if a change is required. This enum is used to
            suspend and resume entitlements using the update method.
          enum:
            - SUSPENDED
            - NORMAL
        customerId:
            type: string
            description: Unique identifier representing a specific customer of the reseller not anonymised. This value will only be sent by Bango if the Merchant and Reseller both approve the sharing of this data
        offerId:
          type: string
          description: |
            The offer given to the user for the merchant service. For example,
            "FREE_FOR_6_MONTHS".
          examples: [FREE_FOR_6_MONTHS]
        status:
          type: string
          examples: [ACTIVE]
          enum:
                  - ACTIVE
                  - SUSPENDED
                  - PENDING
                  - ACTIVE-ENDING
          description: |-
            Entitlement status. Possible values are:
              - "ACTIVE": The entitlement has been successfully activated
              - "SUSPENDED": The entitlement has been suspended.
              - "PENDING": The entitlement has been initiated, but the user has not yet finalized the activation process.
              - "ACTIVE-ENDING": The entitlement is ending at the end of the current period.
        merchantExtensionData:
          $ref: '#/components/schemas/MerchantExtensionData'
        extraInformation:
          $ref: '#/components/schemas/ExtraEntitlementInfo'
        financeData:
          $ref: '#/components/schemas/FinanceDataOutput'
        merchantBangoExtensionData:
          $ref: '#/components/schemas/MerchantBangoExtensionData'
    EntitlementCreate:
      type: object
      required:
        - requestId
        - bangoUserId
        - resellerId
        - productId
      properties:
        requestId:
          type: string
          description: Unique identifier representing a specific entitlement.
          examples: [a25100b8-4e0c-4e37-b921-cac9cb1e930f]
        bangoUserId:
          type: string
          description: Unique identifier representing a specific customer of the reseller as a Bango anonymised value.
          examples: [1549053185]
        sharedCustomerId:
          type: string
          description: Bango generated id shared between reseller and merchant for this customer (contact support for setup)
          examples: [414b3019-0c28-4d14-9c5f-6217b8bd1e3e]
          format: uuid
        resellerId:
          type: string
          description: Unique reseller identifier as agreed with the merchant
          examples: [XYZ_RESELLER]
        productId:
          type: string
          description: 'Entitlement product unique identifier. For example, "BangoMusic".'
          examples: [BangoMusic]
        offerId:
          type: string
          description: |
            The offer given to the user for the merchant service. For example,
            "FREE_FOR_6_MONTHS".
          examples: [FREE_FOR_6_MONTHS]
        customerId:
            type: string
            description: Unique identifier representing a specific customer of the reseller not anonymised. This value will only be sent by Bango if the Merchant and Reseller both approve the sharing of this data
        status:
          type: string
          examples: [PENDING]
          enum:
                  - ACTIVE
                  - SUSPENDED
                  - PENDING
                  - ACTIVE-ENDING
          description: |-
            Entitlement status. Possible values are:
              - "ACTIVE": The entitlement has been successfully activated
              - "SUSPENDED": The entitlement has been suspended.
              - "PENDING": The entitlement has been initiated, but the user has not yet finalized the activation process.
              - "ACTIVE-ENDING": The entitlement is ending at the end of the current period.
        merchantExtensionData:
          $ref: '#/components/schemas/MerchantExtensionData'
        extraInformation:
          $ref: '#/components/schemas/ExtraEntitlementInfo'
        merchantBangoExtensionData:
          $ref: '#/components/schemas/MerchantBangoExtensionData'
    EntitlementCreate202Response:
      type: object
      required:
        - merchantEntitlementId
        - activationUrl
        - expiry
      properties:
        merchantEntitlementId:
          type: string
          description: |
            Unique identifier representing the entitlement as identified by the
            merchant. Value must be URL friendly.
          examples: [a25100b8-4e0c-4e37-b921-cac9cb1e930f]
        activationUrl:
          type: string
          description: URL which the user can follow through to activate the entitlement.
          examples: [https://merchant-website.com/new-entitlement/activation-url]
        expiryTime:
          type: string
          format: date-time
          description: The expiry date for when the URL will no longer be active
          examples: [2020-01-28T14:15:03Z]
    EntitlementCreate200Response:
      type: object
      required:
        - merchantEntitlementId
      properties:
        merchantEntitlementId:
          type: string
          description: |
            Unique identifier representing the entitlement as identified by the
            merchant. Value must be URL friendly.
          examples: [a25100b8-4e0c-4e37-b921-cac9cb1e930f]
    EntitlementCreate201Response:
      type: object
      required:
        - merchantEntitlementId
      properties:
        merchantEntitlementId:
          type: string
          description: |
            Unique identifier representing the entitlement as identified by the
            merchant. Value must be URL friendly.
          examples: [a25100b8-4e0c-4e37-b921-cac9cb1e930f]
    ActivationInfoResponse:
      type: object
      required:
        - merchantEntitlementId
      properties:
        merchantEntitlementId:
          type: string
          description: |
            Unique identifier representing the entitlement as identified by the
            merchant. Value must be URL friendly.
          examples: [a25100b8-4e0c-4e37-b921-cac9cb1e930f]
        activationUrl:
          type: string
          description: URL which the user can follow through to activate the entitlement. For content providers who support an activation code rather than a url, you could return `activationCode` instead of `activationUrl`
          examples: [https://merchant-website.com/new-entitlement/activation-url]
        expiryTime:
          type: string
          format: date-time
          description: The expiry date for when the URL will no longer be active
          examples: [2020-01-28T14:15:03Z]

    EntitlementTerminate:
      type: object
      required:
        - immediate
      description: To determine if the termination is effective immediatly.
      properties:
        immediate:
          type: boolean
          description: |
            Determines if the termination is effective immediately. Immediate
            termination results in HARD edning of the subscription:
              - TRUE
              - FALSE
        reasonCode:
          type: string
          description: |
            Code representing the entitlement revoke reason. This code can be
            any value, but we recommend you use one of the following codes:
              - "FRAUD": The user has not renewed the subscription
              - "ACCOUNT_TERMINATED": The user is no longer a customer
              - "SECURITY": For security reasons, access to this entitlement has been terminated
              - "OTHER": Other
          examples: [FRAUD]
        reasonCategory:
          type: string
          description: |
            String representing the category to which a set of reason codes
            belong to.
        reasonDescription:
          type: string
          description: Description of the entitlement revoke reason
          examples: [Personal data stolen]
        bangoUserId:
          type: string
          description: Unique identifier representing a specific customer of the reseller as a Bango anonymised value.
          examples: [1549053185]
        sharedCustomerId:
          type: string
          description: Bango generated id shared between reseller and merchant for this customer (contact support for setup)
          examples: [414b3019-0c28-4d14-9c5f-6217b8bd1e3e]
          format: uuid
        resellerId:
          type: string
          description: Unique reseller identifier as agreed with the merchant
          examples: [XYZ_RESELLER]
        productId:
          type: string
          description: 'Entitlement product unique identifier. For example, "BangoMusic".'
          examples: [BangoMusic]
        offerId:
          type: string
          description: |
            The offer given to the user for the merchant service. For example,
            "FREE_FOR_6_MONTHS".
          examples: [FREE_FOR_6_MONTHS]
        customerId:
            type: string
            description: Unique identifier representing a specific customer of the reseller not anonymised. This value will only be sent by Bango if the Merchant and Reseller both approve the sharing of this data
        status:
          type: string
          examples: [PENDING]
          enum:
                  - ACTIVE
                  - SUSPENDED
                  - PENDING
                  - ACTIVE-ENDING
          description: |-
            Entitlement status. Possible values are:
              - "ACTIVE": The entitlement has been successfully activated
              - "SUSPENDED": The entitlement has been suspended.
              - "PENDING": The entitlement has been initiated, but the user has not yet finalized the activation process.
              - "ACTIVE-ENDING": The entitlement is ending at the end of the current period.
        merchantExtensionData:
          $ref: '#/components/schemas/MerchantExtensionData'
        extraInformation:
          $ref: '#/components/schemas/ExtraEntitlementInfo'
        financeData:
          $ref: '#/components/schemas/FinanceDataOutput'
        merchantBangoExtensionData:
          $ref: '#/components/schemas/MerchantBangoExtensionData'
    
    ActivationInfo:
      type: object
      required:
        - requestId
        - bangoUserId
        - resellerId
        - productId
        - merchantEntitlementId
      properties:
        requestId:
          type: string
          description: Unique identifier representing a specific entitlement.
          examples: [a25100b8-4e0c-4e37-b921-cac9cb1e930f]
        bangoUserId:
          type: string
          description: Unique identifier representing a specific customer of the reseller as a Bango anonymised value.
          examples: [1549053185]
        sharedCustomerId:
          type: string
          description: Bango generated id shared between reseller and merchant for this customer (contact support for setup)
          examples: [414b3019-0c28-4d14-9c5f-6217b8bd1e3e]
          format: uuid
        resellerId:
          type: string
          description: Unique reseller identifier as agreed with the merchant
          examples: [XYZ_RESELLER]
        productId:
          type: string
          description: 'Entitlement product unique identifier. For example, "BangoMusic".'
          examples: [BangoMusic]
        offerId:
          type: string
          description: |
            The offer given to the user for the merchant service. For example,
            "FREE_FOR_6_MONTHS".
          examples: [FREE_FOR_6_MONTHS]
        customerId:
            type: string
            description: Unique identifier representing a specific customer of the reseller not anonymised. This value will only be sent by Bango if the Merchant and Reseller both approve the sharing of this data
        status:
          type: string
          examples: [CREATED]
          enum:
            - CREATED
          description: |-
            Entitlement status. Possible values are:
              - "CREATED": The entitlement has not yet been activated
        merchantEntitlementId:
          type: string
          examples: [6e37a4b5-8cb9-465b-88a9-ad5eb02596b]
          description: Unique identifier of the entitlement provided by the merchant on creation.
        options:
          type: array
          items:
            type: string
            examples: [SHORT_LIVED_TOKEN]
          description: |-
            Array of optional enum values to determine the type of activation information requested. Available options are 'SHORT_LIVED_TOKEN' and 'LONG_LIVED_TOKEN'.
        merchantExtensionData:
          $ref: '#/components/schemas/MerchantExtensionData'
        extraInformation:
          $ref: '#/components/schemas/ExtraEntitlementInfo'
        financeData:
          $ref: '#/components/schemas/FinanceDataOutput'
        merchantBangoExtensionData:
          $ref: '#/components/schemas/MerchantBangoExtensionData'
    
    EntitlementSuspendResponse:
      type: object
      description: Response for suspend request
      properties:
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
    EntitlementTerminateResponse:
      type: object
      description: Response for termination request
      properties:
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
        terminationDate:
          type: string
          format: date-time
          description: |
            Date and time when the entitlement was or will be terminated, in UTC
            ISO 8601. format (yyyy-MM-ddThh:mm:ssZ)

    ResponseObject:
      type: object
      properties:
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
    BadRequest:
      type: object
      properties:
        responseCode:
          type: string
          examples: [BAD_REQUEST]
        responseMessage:
          type: string
          examples: [Invalid request.]
    Unauthorized:
      type: object
      properties:
        responseCode:
          type: string
          examples: [UNAUTHORIZED]
        responseMessage:
          type: string
          examples: [Invalid access credentials.]
    NotFound:
      type: object
      properties:
        responseCode:
          type: string
          examples: [NOT_FOUND]
        responseMessage:
          type: string
          examples: [Entitlement not found.]
    Conflict:
      type: object
      properties:
        responseCode:
          type: string
          examples: [CONFLICT]
        responseMessage:
          type: string
          examples: [The requested action has been rejected due to a conflict.]
    TooManyRequests:
      type: object
      properties:
        responseCode:
          type: string
          examples: [TOO_MANY_REQUESTS]
        responseMessage:
          type: string
          examples: [Request limit reached. Please try again later.]
    InteralServerError:
      type: object
      properties:
        responseCode:
          type: string
          examples: [INTERNAL_ERROR]
        responseMessage:
          type: string
          examples: [The server encountered an unexpected condition which prevented it from fulfilling the request.]
    ServiceUnavailable:
      type: object
      properties:
        responseCode:
          type: string
          examples: [SERVICE_UNAVAILABLE]
        responseMessage:
          type: string
          examples: [The server is undergoing maintenance and is not available. Please try again later.]
    AlreadyExists:
      type: object
      properties:
        responseCode:
          type: string
          examples: [ALREADY_EXISTS]
        responseMessage:
          type: string
          examples: [Entitlement already exists.]
    InvalidState:
      type: object
      properties:
        responseCode:
          type: string
          examples: [INVALID_STATE]
        responseMessage:
          type: string
          examples: [Operation invalid for the current state of the entitlement.]
    RequestCreated:
      type: object
      properties:
        responseCode:
          type: string
          examples: [CLIENT_ACTION_REQUIRED]
        responseMessage:
          type: string
          examples: [Request created and queued.]

    RequestAccepted:
      type: object
      properties:
        responseCode:
          type: string
          examples: [ACCEPTED]
        responseMessage:
          type: string
          examples: [Request accepted]

    MerchantExtensionData:
      type: object
      description: Private custom key value pairs. Not shared with the reseller
      properties:
        customField1:
          type: string
          examples: [value1]
        customField2:
          type: string
          examples: [value2]
    MerchantBangoExtensionData:
      type: object
      description: Contains a pre-defined list of key-value pairs (added during onboarding) to support static custom data needs
      properties:
        customField1:
          type: string
          examples: [value1]
        customField2:
          type: string
          examples: [value2]

    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]

    CommunicationInformation:
      type: object
      properties:
        msisdn:
         type: string
         examples: ["441234567890"]
        emailAddress:
          type: string
          examples: [example@bango.com]
    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]
    ExtraEntitlementInfo:
      type: object
      properties:
        clientDevice:
          $ref: '#/components/schemas/ClientDevice'
        communicationInformation:
          $ref: '#/components/schemas/CommunicationInformation'
        source:
          $ref: '#/components/schemas/Source'
    FinanceDataOutput:
      type: object
      required:  
        - source
        - type
        - timestamp
      properties:
        source:
          type: string
          description: | 
            the party who added the finance event
          enum:
            - Merchant
            - Reseller
        type:
          type: string
          description: | 
            the type of finance event
          enum:
            - order
            - return
            - renew
        timestamp:
          type: string
          format: date-time
          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: | 
            255 length limit
