openapi: 3.1.0
info:
  version: 1.4.1
  title: Merchant-api-v1
  description: |
    # Change log
    **2026-06-02** | v.1.4.1
    - Updated authentication: replaced single Basic Auth scheme with X-API-Key,
      Basic Auth, and OAuth2 (client credentials) security schemes, aligned with
      Reseller Notifications API
servers:
- url: https://resale.api.sandbox.bango.com 
  description: Integration test environment
- url: https://resale.api.bango.com 
  description: Production environment
security:
  - XApiKey: []
  - BasicAuth: []
  - OAuth2: []
paths:
  '/v1/merchant/echo/{echoString}':
    post:
      tags:
        - Echo
      summary: Check connection
      description: |
        The echo endpoint allows you to check your connection to the Bango resale API. Use it to check the following:
        - You're using the correct base URL
        - You're using the correct credentials
        - The Bango resale API is currently available
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: echoString
          in: path
          description:
            An arbitrary string which is returned in the body of a successful response
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Echo request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EchoResponse'
              examples:
                OK:
                  value:
                    responseCode: OK
                    responseMessage: Success
                    echo: echoString
        '401':
          description: Unauthorized (no response body returned)
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'

  '/v1/merchant/entitlement/activate/{merchantEntitlementId}':
    post:
      summary: Activate an entitlement
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: merchantEntitlementId
          in: path
          description: Your unique identifier of the entitlement
          required: true
          schema:
            type: string
      tags:
        - Entitlement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementActivate'
            examples:
                Basic request:
                  value:
                    activatedDate: 2024-01-01T00:00:00.000Z
                Extended request:
                  value:
                    activatedDate: 2024-01-01T00:00:00.000Z
                    merchantExtensionData: 
                      customField1: value1
                      customField2: value2
                    financeData: 
                      source: Merchant
                      type: order
                      timestamp: 2024-01-01T00:00:00.000Z
                      retailCurrency: USD
                      retailPrice: 0.00
                      retailPriceTax: 0.00
                      offerPrice: 0.00
                      offerPriceTax: 0.00
                      notes: Free text field with 255 character limit
        
      responses:
        '200':
          description: Entitlement activated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized (no response body returned)
        '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/InternalServerError'
            responseCode:
              examples:
                response:
                  value: INTERNAL_ERROR
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
      

  '/v1/merchant/entitlement/{merchantEntitlementId}':
    get:
      summary: Get an entitlement
      description: >
        Entitlement information for the requested unique Entitlement Identifier
        would be returned to be Merchant.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: >-
            Request unique identifier. If present, this id will 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 retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
    patch:
      summary: Update an entitlement
      description: |
        Update an entitlement
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: >-
            Request unique identifier. If present, this id will 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 updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                InvalidAPIRequest:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                NotSupported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
        '401':
          description: Unauthorized (no response body returned)
        '403':
          description: Unable to create entitlement for the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                NotAvailable:
                  value:
                    responseCode: NOT_AVAILABLE
                    responseMessage: No active entitlement routes found.
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                NotFound:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
        '409':
          description: Entitlement not in the correct state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                InvalidState:
                  value:
                    responseCode: INVALID_STATE
                    responseMessage: Operation invalid for the current state of the entitlement.
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                TooManyRequests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                InternalError:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                ServiceUnavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: 
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdate'

                  
        description: The entitlement activation JSON.
        required: true

  '/topups/entitlements/{entitlementId}':
    get:
      tags:
        - Entitlement
      summary: Get recent top ups
      description: |
        Both resellers and merchants can get top up information associated to the Bango entitlementId. The response only returns top ups created in the last 90 days.

        The response returns all dates associated to the top ups, as well as information on when the entitlement will end, and what action will be taken at that time, e.g. either a SUSPEND or TERMINATE_IMMEDIATE request will be sent automatically to the merchant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopUpsCreateRequest'
            examples:
              BaseRequest:
                value:
                 topUps:
                   productKey: MUSIC_10_DAYS
      responses:
        '200':
          description: Top ups returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpsCreateSuccessResponse'
              examples:
                OK:
                  value:
                    entitlementId: 1926b2fc-6700-4000-8259-7872a1733301
                    topUpsExpiry:
                      ts: "2024-10-08T08:12:26.022Z"
                      behavior: "SUSPEND"
                    topUps:
                        topUpId: "1926b2fc-6700-4000-8bac-4e1984f6d301"
                        productKey: "MUSIC_5_DAYS"
                        createdTs: "2024-10-08T08:12:26.022Z"
                        startTs: "2024-10-08T08:12:26.022Z"
                        endTs: "2024-10-08T08:12:26.022Z"
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpsGetRequest404'
              examples:
                Not found:
                  value:
                    responseMessage: Variable error message providing more information about what went wrong
                    metadata:
                      responseMessageFrom: BANGO


  '/v1/merchant/entitlement/report':
    post:
      summary: Search for entitlements
      description: Get a list of entitlements for a bangoUserId or sharedCustomerId, matching specific criteria
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: >-
            Request unique identifier. If present, this id will be used for
            idempotency.
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      responses:
        '200':
          description: Retrieval successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementReportResponse'
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                InvalidAPIRequest:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                NotSupported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
        '401':
          description: Unauthorized (no response body returned)
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                TooManyRequests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                InternalError:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              examples:
                ServiceUnavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage:           
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementReport'
        description: The report filters JSON.
        required: true        

  '/v1/merchant/entitlement/notify/{merchantEntitlementId}':
    post:
      summary: Send a notification
      description: |
        Send a notification relating to an entitlement which does not change the state of the entitlement.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: >-
            Request unique identifier. If present, this id will 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: Notification sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotifyResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized (no response body returned)
        '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/InternalServerError'
            responseCode:
              examples:
                response:
                  value: INTERNAL_ERROR
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notify'
        description: The notification JSON.
        required: true

  '/v1/merchant/entitlement/suspend/{merchantEntitlementId}':
    post:
      summary: Suspend an entitlement
      description: |
        Call this endpoint to suspend an entitlement.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: >-
            Request unique identifier. If present, this id will 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 suspended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    requestId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    productId: MUSIC
                    entitlementDisplayName: 30 days Bango music
                    offerId: null
                    resellerId: BANGO_TEL
                    activationCode: null
                    dateCreated: "2024-06-22T17:35:38.92Z"
                    dateActivated: "2024-06-225T17:35:38.92Z"
                    dateSuspended: "2024-00-01T32:29:140Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateExpiry: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: SUSPENDED
                    merchantExtensionData: 
                      customField1: value1
                      customField2: value2
                    extraInformation:
                      communicationInformation:
                        emailAddress: 123@abc.co.uk
                        msisdn: "441234567890"
                      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: Firefox
                      source: 
                        channelType: Website
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: East Anglia
                        brand: BrandABC
                    financeData: 
                      source: "Merchant"
                      type: "order"
                      timestamp: "2021-10-18T11:09:44Z"
                    merchantBangoExtensionData:
                      routeKey1: value1
                      routeKey2: value2

        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized (no response body returned)
        '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/InternalServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
  '/v1/merchant/entitlement/resume/{merchantEntitlementId}':
    post:
      summary: Resume an entitlement
      description: |
        Call this endpoint to resume a suspended entitlement. You can optionally change the productId at the same time.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: >-
            Request unique identifier. If present, this id will 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:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeRequest'
      responses:
        '200':
          description: Entitlement suspended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    requestId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    productId: MUSIC
                    entitlementDisplayName: 30 days Bango music
                    offerId: null
                    resellerId: BANGO_TEL
                    activationCode: null
                    dateCreated: "2024-06-22T17:35:38.92Z"
                    dateActivated: "2024-06-225T17:35:38.92Z"
                    dateSuspended: "2024-00-01T32:29:140Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateExpiry: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: ACTIVE
                    merchantExtensionData: 
                      customField1: value1
                      customField2: value2
                    extraInformation:
                      communicationInformation:
                        emailAddress: 123@abc.co.uk
                        msisdn: "441234567890"
                      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: Firefox
                      source: 
                        channelType: Website
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: East Anglia
                        brand: BrandABC
                    financeData: 
                      source: "Merchant"
                      type: "order"
                      timestamp: "2021-10-18T11:09:44Z"
                    merchantBangoExtensionData:
                      routeKey1: value1
                      routeKey2: value2

        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized (no response body returned)
        '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/InternalServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
  '/v1/merchant/entitlement/terminate/{merchantEntitlementId}':
    post:
      summary: Terminate an entitlement
      description: |
        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. If present, this id will 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:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementTerminate'
      responses:
        '200':
          description: Entitlement terminated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    requestId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    productId: MUSIC
                    entitlementDisplayName: 30 days Bango music
                    offerId: null
                    resellerId: BANGO_TEL
                    activationCode: null
                    dateCreated: "2024-06-22T17:35:38.92Z"
                    dateActivated: "2024-06-225T17:35:38.92Z"
                    dateSuspended: "2024-08-01T32:29:140Z"
                    dateEnded: "2024-09-30T45:12:55Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateExpiry: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: REVOKED
                    merchantExtensionData: 
                      customField1: value1
                      customField2: value2
                    extraInformation:
                      communicationInformation:
                        emailAddress: 123@abc.co.uk
                        msisdn: "441234567890"
                      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: Firefox
                      source: 
                        channelType: Website
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: East Anglia
                        brand: BrandABC
                    financeData: 
                      source: "Merchant"
                      type: "order"
                      timestamp: "2021-10-18T11:09:44Z"
                    merchantBangoExtensionData:
                      routeKey1: value1
                      routeKey2: value2
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized (no response body returned)
        '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/InternalServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
      
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://auth.bango.com/oath2/token
          scopes:
            any: grants Bango access to the merchant system based on merchant defined rules
  schemas:
    TopUpsGetRequest:
      Type: object
      properties:
        entitlementId: uuid
        topUpsExpiry:
          properties: 
            ts: date-time
            behavior: enum
        topUps:
          properties: 
            topUpId: uuid
            productKey: string
            createdTs: date-time
            startTs: date-time
            endTs: date-time
    TopUpsGetRequest404:
      Type: object
      properties:
        responseMessage: string
        metadata:
          responseMessageFrom: string
    TopUpsCreateRequest:
      Type: object
      properties:
        topUps*:
           properties:
            productKey*: string
    TopUpsCreateSuccessResponse:
      Type: object
      properties:
        entitlementId: uuid
        topUpsExpiry:
          ts: date-time
          behavior: enum
        topUps:
          topUpId: uuid
          productKey: string
          createdTs: date-time
          startTs: date-time
          endTs: date-time
    TopUpsCreateErrorResponse:
      Type: object
      properties:
        responseMessage: string
        metadata:
          responseMessageFrom: string
    ResponseObject:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
    EchoResponse:
      type: object
      properties:
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
        echo:
          type: string
          examples: ["{echoString}"]
    ErrorResponseObject:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
    BadRequest:
      type: object
      properties:
        responseCode:
          type: string
          examples: [BAD_REQUEST]
        responseMessage:
          type: string
          examples: [Invalid request]
    NotFound:
      type: object
      properties:
        responseCode:
          type: string
          examples: [NOT_FOUND]
        responseMessage:
          type: string
          examples: [Entitlement not found]
    TooManyRequests:
      type: object
      properties:
        responseCode:
          type: string
          examples: [TOO_MANY_REQUESTS]
        responseMessage:
          type: string
          examples: [Request limit reached. Please try again later]
    InternalServerError:
      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]
    InvalidState:
      type: object
      description: The Bango Platform didn't process the request because the entitlement is
        not in correct state.
      properties:
        responseCode:
          type: string
          examples: [INVALID_STATE]
        responseMessage:
          type: string
          examples: [Operation invalid for the current state of the entitlement.]
    EntitlementActivate:
      type: object
      required:
        - activatedDate
      properties:
        activatedDate:
          type: string
          format: date-time
          description: Date when the entitlement was activated.
          examples: [2024-10-14T15:34:49Z]
        merchantExtensionData:
          $ref: '#/components/schemas/MerchantExtensionData'
        financeData:
          $ref: '#/components/schemas/FinanceData'
    Notify:
      type: object
      required:
        - notification
      properties:
        notification:
          type: string
          format: enum
          examples: [ACCOUNT_UNLINKED]
          description: |-
            The following notifications are supported:
              - `ACCOUNT_UNLINKED`: The entitlement has been unlinked from its (merchant-side) account. Entitlement may be inaccessible by the customer and recovery action is required.
              - `ACCOUNT_LINKED`: The entitlement has been linked to a (merchant-side) account.
    NotifyResponse:
      type: object
      properties:
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
    ResumeRequest:
      type: object
      properties:
        productId:
          type: string
          examples: [MUSIC]
    EntitlementUpdate:
      type: object
      required:
        - merchantEntitlementId
      properties:
        productId:
          type: string
          examples: [MUSIC]
        merchantExtensionData:
          $ref: '#/components/schemas/MerchantExtensionData'
        financeData:
          $ref: '#/components/schemas/FinanceData'
    EntitlementTerminate:
      type: object
      required:
        - terminatedDate
      properties:
        immediate:
          type: boolean
          description: |
            Determines if the termination is effective immediately. If nothing is passed, the value will default to TRUE.
            Immediate termination results in HARD ending of the entitlement:
            - TRUE
            - FALSE
        terminatedDate:
          type: string
          format: date
          description: Date when the entitlement was terminated.
          examples: [2024-10-14T15:34:49Z]
        reasonCategory:
          type: string
          enum: [CUSTOMER_CANCELLED, REVOKED]
          description: High level category for the type of termination. 
        reasonCode:
          type: string
          enum: [NOT_RENEWED, CHANGED_SERVICE, SUBSCRIPTION_CANCELLED, ADDON_CANCELLED, EXPIRED, ACCOUNT_TERMINATED, SUSPEND_TERMINATED, ERROR, FRAUD, IMMEDIATE_CANCELLATION, OTHER]
          description: Code representing the entitlement cancel or revoke reason. More information can be found here "https://developer.bango.info/categories-and-codes/"
          examples: [FRAUD]
        reasonDescription:
          type: string
          description: Description of the entitlement revoke reason
          examples: [Personal data stolen]
        merchantExtensionData:
          $ref: '#/components/schemas/MerchantExtensionData'
        financeData:
          $ref: '#/components/schemas/FinanceData'
    EntitlementReport:
      type: object
      description: List of filters applied to retrieve a list of existing entitlements
      required:
        - resellerId
      properties:
        resellerId:
          type: string
          description: Unique identifier for the content provider
          examples: [BANGO_TEL]
        bangoUserId:
          type: string
          description: Unique, immutable user identifier 
          examples: [29132482-7c51-4fc3-9f41-5497371d5590]
        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]
        productId:
          type: string
          description: Unique identifier for the product/offer
          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. 
    EntitlementReportResponse:
      type: object
      properties:
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
        entitlements:
          type: array
          items:
            type: object
            properties:
              merchantEntitlementId:
                type: string
                description: Merchants unique identifier representing an entitlement.
                examples: [6673b39e-8302-412d-bbdb-446c96c34871]
              requestId:
                type: string
                description: Bango unique identifier representing an entitlement.
                examples: [981a55a5-b3a4-46dc-9fac-a86227b26344]
              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
                examples: ["123456789"]
              bangoUserId:
                type: string
                description: Unique, immutable user identifier 
                examples: [29132482-7c51-4fc3-9f41-5497371d5590]
              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]
              resellerId:
                type: string
                description: Unique identifier for the content provider
                examples: [BANGO_TEL]
              productId:
                type: string
                description: Unique identifier for the product/offer
                examples: [MUSIC]
              offerId:
                type: string
                description: Entitlement offer identifier
                examples: [BUNDLE]
              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. 

              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]
              merchantExtensionData:
                $ref: '#/components/schemas/MerchantExtensionData'
              extraInformation:
                $ref: '#/components/schemas/ExtraInformation'
              financeData:
                $ref: '#/components/schemas/FinanceData'
              merchantBangoExtensionData:
                $ref: '#/components/schemas/MerchantBangoExtensionData' 


    
    EntitlementResponse:
      type: object
      properties:
        requestId:
          type: string
          description: Unique identifier representing a specific entitlement
        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
          examples: ["123456789"]
        bangoUserId:
          type: string
          description: Unique, immutable user identifier 
          examples: [29132482-7c51-4fc3-9f41-5497371d5590]
        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]
        resellerId:
          type: string
          description: Unique identifier for the content provider
          examples: [BANGO_TEL]
        productId:
          type: string
          description: Unique identifier for the product/offer
          examples: [MUSIC]
        offerId:
          type: string
          description: Entitlement offer identifier
          examples: [BUNDLE]
        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. 
        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]
        responseMessage:
          type: string
          examples: [Success]
        merchantExtensionData:
          type: object
          $ref: '#/components/schemas/MerchantExtensionData'
        extraInformation:
          type: object
          $ref: '#/components/schemas/ExtraInformation'
        financeData:
          type: object
          $ref: '#/components/schemas/FinanceData'
        merchantBangoExtensionData:
          type: object
          $ref: '#/components/schemas/MerchantBangoExtensionData'
    MerchantExtensionData:
      type: object
      description: Custom key value pairs
      properties:
        customField1:
          type: string
          examples: [value1]
        customField2:
          type: string
          examples: [value2]  
    MerchantBangoExtensionData:
      type: object
      additionalProperties:
        type: string
        description: Contains a list of pre-defined key-value pairs, set at the route level and provided during onboarding.
      properties:
        routeKey1:
          type: string
          examples: [value1]
        routeKey2:
          type: string
          examples: [value2]     
    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
    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]