openapi: 3.1.0

info:
  title: Entitlements
  version: 1.4.2
  description: |
    # Overview
    This API enables the reseller to send requests to manage an entitlement's lifecycle. Resellers wanting a simple point-to-point integration can use this API to manage the full lifecycle of an entitlements.

    For resellers wanting to integrate with offer management, bundling and for Bango to handle some of the more complex lifecycle flows, the Consumer Offer API is recommended for the create flow.

    # Change log
    **2026-06-02** | v.1.4.2
    - Updated authentication: replaced single Basic Auth scheme with X-API-Key,
      Basic Auth, and OAuth2 (client credentials) security schemes, aligned with
      Reseller Notifications API

    **2025-06-12** | v.1.4.1
    - Overview & change log added

    **2024-09-04** | v.1.4.0
    - Top ups released

    **2023-08-14** | v.1.3.0
    - Added reseller-initiated /activationInfo endpoint
    - Added metadata to error responses to identify whether the error originated from Bango or the merchant. This is to help resellers resolve integration issues more easily.
    
    **2022-09-22** | v.1.2.0
    - Added Bango-generated sharedCustomerId to reseller notifications, merchant requests and all responses

    **2021-08-05** | v.1.1.0
    - Added extensionData for resellers
    - Added merchantExtensionData for merchants
    - Added financeData to relevant merchant-initiated API requests, reseller notifications and all responses
    - Added merchantBangoExtensionData for merchant requests and responses
    - Added externalEntitlementId for resellers

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

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: []

tags:
  - name: Echo
    description: Check your connection to the Bango resale API
  - name: Entitlement
    description: Manage the lifecycle of your entitlements
  - name: Top Ups 
    description: Top up short-lived entitlements for automated duration extension and suspend/terminate flows

paths:
  '/v1/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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '501':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
  '/v1/entitlement':
    post:
      tags:
        - Entitlement
      summary: Create an entitlement
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: x-request-id
          in: header
          description: Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: x-operation-id
          in: header
          description: Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementRequest'
            examples:  
              BaseRequest:
                value:
                  customerIdentifier: "123456789"
                  merchantAccountKey: BANGO_US
                  productKey: MUSIC
                  notificationUrl: https://notifications.bango.com
              ExtendedRequest:
                value:
                  customerIdentifier: "123456789"
                  merchantAccountKey: BANGO_US
                  productKey: MUSIC
                  notificationUrl: https://notifications.bango.com
                  entitlementDisplayName: 30 day free trial for Bango Music
                  offerKey: BUNDLE_X
                  externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                  dateExpiry: 2024-12-05T07:46:52Z
                  dateAutoSuspend: 2024-09-05T07:46:52Z
                  extensionData: 
                    customField1: value1
                    customField2: value2
                  extraInformation:
                    communicationInformation:
                      emailAddress: example@bango.com
                      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: Chrome
                    source: 
                      channelType: Retail
                      campaignRef: SUMMER_PROMO
                      referrer: SEARCH_ENGINE
                      bundleId: BundleABC123
                      country: United Kingdom
                      region: CB1 3ED
                      brand: BrandA
      responses:
        '200':
          description: Entitlement created and activated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEntitlementResponse'
              examples:
                OK:
                  value:
                    customerIdentifier: "123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    merchantAccountKey: BANGO_US
                    productKey: MUSIC
                    entitlementDisplayName: 30 day free trial for Bango Music
                    offerKey: null
                    activationCode: null
                    dateCreated: "2024-06-22T17:35:38.92Z"
                    dateActivated: "2024-06-22T17:35:59.90Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      customField1: value1
                      customField2: value2
                    parameters:
                    extraInformation:
                      communicationInformation:
                        emailAddress: example@bango.com
                        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: Chrome
                      source: 
                        channelType: Retail
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: CB1 3ED
                        brand: BrandA
        '201':
          description: Entitlement created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEntitlementResponse'
              examples:
                Created:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    merchantAccountKey: BANGO_US
                    productKey: MUSIC
                    entitlementDisplayName: 30 day free trial for Bango Music
                    offerKey: null
                    activationCode: null
                    dateCreated: "2024-06-22T17:35:38.92Z"
                    dateActivated: "0001-01-01T00:00:00Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: "0001-01-01T00:00:00Z"
                    responseCode: CREATED
                    responseMessage: Entitlement Created
                    status: PENDING
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      customField1: value1
                      customField2: value2
                    parameters:
                    extraInformation:
                      communicationInformation:
                        emailAddress: example@bango.com
                        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: Chrome
                      source: 
                        channelType: Retail
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: CB1 3ED
                        brand: BrandA
        '202':
          description: 'Entitlement created successfully, action required to activate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEntitlementResponse'
              examples:
                ClientActionRequired:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    merchantAccountKey: BANGO_US
                    productKey: MUSIC
                    entitlementDisplayName: 30 day free trial for Bango Music
                    offerKey: null
                    activationCode: null
                    dateCreated: "2024-06-22T17:35:38.92Z"
                    dateActivated: "2024-06-22T17:35:59.90Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: "0001-01-01T00:00:00Z"
                    responseCode: CLIENT_ACTION_REQUIRED
                    responseMessage: An action is required to be performed by the client.
                    status: PENDING
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      customField1: value1
                      customField2: value2
                    parameters:
                      Action: NAVIGATE_TO_URL
                      Url: https://example.activation.url.bango.com
                    extraInformation:
                      communicationInformation:
                        emailAddress: example@bango.com
                        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: Chrome
                      source: 
                        channelType: Retail
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: CB1 3ED
                        brand: BrandA
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Max entitlements per user:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: "Invalid request or the request contains invalid data. Maximum number of subscriptions for user reached. Existing Active EntitlementId: f8069c89-bb3a-441c-a055-f56cccd91e1a"
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Unable to create entitlement for the route requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Route not recognized. Please check your merchantAccountKey or contact Bango support.
                    metadata:
                      responseMessageFrom: BANGO
        '409':
          description: Entitlement ID already in use
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Already exists:
                  value:
                    responseCode: ALREADY_EXISTS
                    responseMessage: Entitlement already exists.
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
 
    patch:
      summary: Update an entitlement
      operationId: UpdateEntitlement 
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: x-request-id
          in: header
          description: Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: x-operation-id
          in: header
          description: Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
      tags:
        - Entitlement
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdate'
            examples:    
              Product update:
                value:
                  entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497
                  productKey: MUSIC_PREMIUM
              Date expiry update:
                value:
                  entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497
                  dateExpiry: 2024-12-05T07:46:52Z
              Auto suspend date update:
                value:
                  entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497
                  dateAutoSuspend: 2024-09-05T07:46:52Z
              Notification Url update:
                value:
                  entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497
                  notificationUrl: https://www.example2.com/notification/a25100b8-4e0c-4e37-b921-cac9cb1e930f
              Customer Identifier update:
                value:
                  entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497
                  customerIdentifier: "4407987654321"
              External entitlementId update:
                value:
                  entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497
                  externalEntitlementId: c843678f-d45a-49f4-868d-2bbc445b2c2e
        description: The entitlement JSON you want to update
        required: true
      responses:
        '200':
          description: Entitlement updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:36:01Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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
        '202':
          description: An action is required to be performed by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                Accepted:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:36:01Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: ACCEPTED
                    responseMessage: Update request accepted by merchant.
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                      Action: NAVIGATE_TO_URL
                      Url: https://example.com/?entitlementId=a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    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    
                ClientActionRequired:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:36:01Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: CLIENT_ACTION_REQUIRED
                    responseMessage: An action is required to be performed by the client.
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                      Action: NAVIGATE_TO_URL
                      Url: https://example.com/?entitlementId=a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    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
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '403':
          description: Unable to create entitlement for the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not available:
                  value:
                    responseCode: NOT_AVAILABLE
                    responseMessage: No active entitlement routes found.
                    metadata:
                      responseMessageFrom: BANGO
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
                    metadata:
                      responseMessageFrom: BANGO
        '409':
          description: Entitlement not in the correct state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid state:
                  value:
                    responseCode: INVALID_STATE
                    responseMessage: Operation invalid for the current state of the entitlement.
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
      
    get:
      summary: Get an entitlement using externalEntitlementId
      description: Get information about an entitlement using external entitlement id.
      operationId: get
      parameters:
      - name: X-RequestIdentifier
        in: header
        description: Optional identifier to support idempotency
        schema:
          type: string
          format: uuid
      - name: ExternalEntitlementId
        in: header
        required: true
        description: >-
          Unique identifier provided for the entitlement by the Reseller
        schema:
          type: string
      tags:
        - Entitlement
      responses:
        '200':
          description: Entitlement retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:36:01Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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"
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                InternalError:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
  '/v1/entitlement/{entitlementId}':
    get:
      summary: Get an entitlement
      description: |
        Get information about an entitlement.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: entitlementId
          in: path
          required: true
          description: The Bango `entitlementId` generated when the entitlement is created
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      responses:
        '200':
          description: Entitlement retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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"
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage:
                    metadata:
                      responseMessageFrom: BANGO
  '/v1/entitlement/activationInfo/{entitlementId}':
    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: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: x-request-id
          in: header
          description: Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: x-operation-id
          in: header
          description: Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: entitlementId
          in: path
          description: >-
            Bango generated unique identifier of the entitlement 
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      requestBody:
        description: Request example
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivationInfo'
            examples:    
              Extended request:
                value:
                  options: [SHORT_LIVED_TOKEN]
      responses:
        '200':
          description: Activation information returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivationInfoResponse'
              examples:
                activation url:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    responseCode: CLIENT_ACTION_REQUIRED
                    responseMessage: An action is required to be performed by the client.
                    parameters:
                      action: NAVIGATE_TO_URL
                      url: https://example.com/?entitlementId=a25100b8-4e0c-4e37-b921-cac9cb1e930f 
                      urlExpiry: '0001-01-01T00:00:000Z'
                activation code:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    responseCode: CLIENT_ACTION_REQUIRED
                    responseMessage: An action is required to be performed by the client.
                    activationCode: STB45454
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found.
                    metadata:
                      responseMessageFrom: BANGO
                    
        '409':
          description: Entitlement already active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Already active:
                  value:
                    responseCode: ALREADY_ACTIVE
                    responseMessage: Entitlement is already active.
                    metadata:
                      responseMessageFrom: BANGO
                Invalid status:
                  value:
                    responseCode: INVALID_STATUS
                    responseMessage: Entitlement is not in a pending status.
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO

  '/v1/entitlement/accountRecovery/{entitlementId}':
    post:
      tags:
        - Entitlement
      summary: Account recovery
      description: |
        Use this to recover the customer's account for a given entitlement.

        Please note that the base url for this endpoint is different:
        - Sandbox: https://acr-b33f-resale.eu.uat.integrator.bango.com
        - Production - US region: https://acr-b33f-resale.us.integrator.bango.com
        - Production - EU region: https://acr-b33f-resale.eu.integrator.bango.com
        - Production - AP region: https://acr-b33f-resale.ap.integrator.bango.com 
      operationId: account_recovery_v1_entitlement_accountRecovery__entitlement_id__post
      parameters:
        - name: x-request-id
          in: header
          description: Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: x-operation-id
          in: header
          description: Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: entitlementId
          in: path
          description: Bango generated unique identifier of the entitlement 
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementAccountRecoveryRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountRecoveryResponse'
              examples:
                Success:
                  value:
                    responseCode: Ok
                    responseMessage: Success
                    recoveryUrl: https://example.activation.url.bango.com
                    expiryTs: "2024-06-17T20:38:39Z"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AC-BadRequestResponse'
              examples:
                Bad request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AC-AuthorizationErrorResponse'
              examples:
                Not authorized:
                  value:
                    responseCode: UNAUTHORIZED
                    responseMessage: You have not provided adequate credentials to access this resource.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AC-NotFoundResponse'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Resource not found
        '409':
          description: Invalid State
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AC-InvalidStateResponse'
              examples:
                Conflict:
                  value:
                    responseCode: INVALID_STATE
                    responseMessage: The entitlement is not in the correct state to be recovered.
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AC-TooManyRequestsResponse'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit has been reached
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AC-InternalErrorResponse'    
              examples:
                Internal server error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: The server encountered an unexpected condition which prevented it from fulfilling the request.
        '503':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AC-ServiceUnavailableResponse'    
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: null

  '/v1/entitlement/report':
    post:
      summary: Search for entitlements
      description: |
        Get a list of entitlements for a customerIdentifier, matching specific criteria
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support 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/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage:     
                    metadata:
                      responseMessageFrom: BANGO 
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementReport'
        description: The report filters JSON.
        required: true       
  '/v1/entitlement/suspend/{entitlementId}':
    post:
      summary: Suspend an entitlement
      description: |
        This operation can only be performed on entitlements that are in ACTIVE status.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: x-request-id
          in: header
          description: Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: x-operation-id
          in: header
          description: Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: entitlementId
          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:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:35:59.90Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateFailed: "0001-01-01T00:00:00Z"
                    dateSuspended: "2020-06-23T08:14:41.003Z"
                    dateResumed: null
                    responseCode: OK
                    responseMessage: Subscription suspended successfully
                    status: SUSPENDED
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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: Firefox
                      communicationInformation:
                        emailAddress: 123@abc.co.uk
                        msisdn: "441234567890"
                      source: 
                        channelType: Website
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: East Anglia
                        brand: BrandABC
                        serviceFlow: Activation
        '202':
          description: Suspend request accepted by mechant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                Accepted:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:35:59.90Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateFailed: "0001-01-01T00:00:00Z"
                    dateSuspended: "2020-06-23T08:14:41.003Z"
                    dateResumed: null
                    responseCode: ACCEPTED
                    responseMessage: Suspend request accepted by merchant.
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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: Firefox
                      communicationInformation:
                        emailAddress: 123@abc.co.uk
                        msisdn: "441234567890"
                      source: 
                        channelType: Website
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: East Anglia
                        brand: BrandABC
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '403':
          description: Unable to create entitlement for the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not available:
                  value:
                    responseCode: NOT_AVAILABLE
                    responseMessage:
                    metadata:
                      responseMessageFrom: BANGO
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
                    metadata:
                      responseMessageFrom: BANGO
        '409':
          description: Entitlement not in the correct state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid state:
                  value:
                    responseCode: INVALID_STATE
                    responseMessage: Operation invalid for the current state of the entitlement.
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
  '/v1/entitlement/resume/{entitlementId}':
    post:
      summary: Resume an entitlement
      description: |
        This operation can only be performed on entitlements that are in SUSPENDED status. The entitlement will be returned to the status it was in prior to being suspended.
        
        You can optionally choose to change the `productKey` when resuming the entitlement.
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: x-request-id
          in: header
          description: Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: x-operation-id
          in: header
          description: Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: entitlementId
          in: path
          description: Unique identifier used on activation.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeRequest'
            examples:  
              BaseRequest:
                value:
                  productKey: "MUSIC"
      responses:
        '200':
          description: Entitlement resumed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:35:59.90Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateFailed: "0001-01-01T00:00:00Z"
                    dateSuspended: "2020-06-23T08:14:41.00Z"
                    dateResumed: null
                    responseCode: OK
                    responseMessage: Entitlement resumed successfully
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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: Firefox
                      communicationInformation:
                        emailAddress: 123@abc.co.uk
                        msisdn: "441234567890"
                      source: 
                        channelType: Website
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: East Anglia
                        brand: BrandABC
        '202':
          description: Resume request accepted by merchant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                Accepted:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:35:59.90Z"
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateFailed: "0001-01-01T00:00:00Z"
                    dateSuspended: "2020-06-23T08:14:41.00Z"
                    dateResumed: null
                    responseCode: ACCEPTED
                    responseMessage: Resume request pending
                    status: SUSPENDED
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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: Firefox
                      communicationInformation:
                        emailAddress: 123@abc.co.uk
                        msisdn: "441234567890"
                      source: 
                        channelType: Website
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: East Anglia
                        brand: BrandABC
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Operation not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
                Invalid productKey:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid product key
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '403':
          description: Unable to create entitlement for the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not available:
                  value:
                    responseCode: NOT_AVAILABLE
                    responseMessage: No active entitlement routes found.
                    metadata:
                      responseMessageFrom: BANGO
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
                    metadata:
                      responseMessageFrom: BANGO
        '409':
          description: Entitlement not in the correct state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid state:
                  value:
                    responseCode: INVALID_STATE
                    responseMessage: Operation invalid for the current state of the entitlement.
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage:
                    metadata:
                      responseMessageFrom: BANGO
  '/v1/entitlement/cancel/{entitlementId}':
    post:
      summary: Cancel an entitlement
      description: |
        Cancel an entitlement
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: x-request-id
          in: header
          description: Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: x-operation-id
          in: header
          description: Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: entitlementId
          in: path
          description: Unique identifier used on activation.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      responses:
        '200':
          description: Entitlement cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:35:59.90Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: ACTIVE-ENDING
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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
        '202':
          description: Entitlement cancellation request pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                Accepted:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: ACCEPTED
                    responseMessage: Termination request accepted by merchant.
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    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
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '403':
          description: Unable to create entitlement for the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not available:
                  value:
                    responseCode: NOT_AVAILABLE
                    responseMessage: No active entitlement routes found.
                    metadata:
                      responseMessageFrom: BANGO
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
                    metadata:
                      responseMessageFrom: BANGO
        '409':
          description: Request could not be completed due to a conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Conflict:
                  value:
                    responseCode: CONFLICT
                    responseMessage: The requested action has been rejected due to a conflict.
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage:
                    metadata:
                      responseMessageFrom: BANGO
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementTerminate'
            examples:    
              BaseRequest:
                value:
                  cancelReasonCategory: CUSTOMER_CANCELLED
                  cancelReasonCode: NOT_RENEWED
                  cancelReasonDescription: The user did not renew their monthly contract
  '/v1/entitlement/revoke/{entitlementId}':
    post:
      summary: Revoke an entitlement
      description: |
        Revoke an entitlement
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: x-request-id
          in: header
          description: Unique request id generated by the reseller. Useful for e2e trouble-shooting. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: x-operation-id
          in: header
          description: Reseller-generated unique id per operation. Used by some content providers to identify an idempotent retry. While listed as an optional header, some content providers consider this to be mandatory.
          schema:
            type: string
        - name: entitlementId
          in: path
          description: Unique identifier used on activation.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Entitlement
      responses:
        '200':
          description: Entitlement revoke successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "2020-06-22T17:35:59.90Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: OK
                    responseMessage: Success
                    status: REVOKED
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    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
        '202':
          description: Entitlement cancellation request pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                Accepted:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: "4407123456789"
                    sharedCustomerId: "414b3019-0c28-4d14-9c5f-6217b8bd1e3e"
                    bangoUserId: "2147483647"
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: "2020-06-22T17:35:38.92Z"
                    dateActivated: "0001-01-01T00:00:00Z"
                    dateExpiry: "0001-01-01T00:00:00Z"
                    dateAutoSuspend: null
                    dateEnded: "0001-01-01T00:00:00Z"
                    dateFailed: "0001-01-01T00:00:00Z"
                    responseCode: ACCEPTED
                    responseMessage: Termination request accepted by merchant.
                    status: ACTIVE
                    externalEntitlementId: "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"
                    extensionData: 
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters:
                    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
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API  request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '403':
          description: Unable to create entitlement for the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not available:
                  value:
                    responseCode: NOT_AVAILABLE
                    responseMessage: No active entitlement routes found.
                    metadata:
                      responseMessageFrom: BANGO
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
                    metadata:
                      responseMessageFrom: BANGO
        '409':
          description: Request could not be completed due to a conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Conflict:
                  value:
                    responseCode: CONFLICT
                    responseMessage: The requested action has been rejected due to a conflict.
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Internal error:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: 
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage:
                    metadata:
                      responseMessageFrom: BANGO
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementTerminate'
            examples:    
              Base request:
                value:
                  cancelReasonCategory: ACTIVATION_ROLLBACK
                  cancelReasonCode: FRAUD
                  cancelReasonDescription: Personal data stolen

  '/topups/entitlements/{entitlementId}':
    post:
      summary: Create top ups
      description: |
        Only resellers are permitted to create top ups. 
        
        You must include the idempotency header **X-RequestIdentifier** to ensure you do not accidentally add a top up multiple times to an entitlement in the event of an unexpected response (e.g. a timeout). You can also use the Get endpoint to check what top ups have been created for the entitlement.

        New top ups are automatically stacked to extend the duration of the entitlement.

        A suspended entitlement will be re-activated automatically. 

        The 201 (created) response returns all dates associated to the top ups requested, as well as information on when the entitlement will now 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.
      tags:
        - Top Ups 
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Unique request identifier which supports idempotency
          required: true
          schema:
            type: string
        - name: entitlementId
          in: path
          description: Bango's unique id of the entitlement
          required: true
          schema:
            type: string
            format: uuid 
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopUpRequest'
      responses:
        201:
          description: Top up created  
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpResponse'
        400:
          description: Bad request 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BangoErrorResponse'
        401:
          description: Unauthorized (no response body returned)
        404:
          description: Entitlement not found 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BangoErrorResponse'
        409:
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BangoErrorResponse'
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BangoErrorResponse'
        503:
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BangoErrorResponse'
    get:
      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.
      tags:
        - Top Ups
      responses:
        200:
          description: Top ups returned 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpResponse'
              examples:
                Top ups returned:
                  value:
                    entitlementId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    topUpsExpiry:
                        ts: 2024-05-18T03:12:23.122Z
                        behavior: SUSPEND
                    topUps:
                        - topUpId: c21309d7-652e-4b32-9547-97b6b08ce31e
                          productKey: MUSIC_5_DAYS
                          createdTs: 2024-05-03T03:12:23.123Z
                          startTs: 2024-05-03T03:12:23.123Z
                          endTs: 2024-05-08T03:12:23.122Z
                        - topUpId: c21309d7-652e-4b32-9547-97b6b08ce31e
                          productKey: MUSIC_10_DAYS
                          createdTs: 2024-05-06T14:37:54.324Z
                          startTs: 2024-05-08T03:12:23.123Z
                          endTs: 2024-05-18T03:12:23.122Z
        401:
          description: Unauthorized (no response body returned)
        404:
          description: Entitlement not found 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BangoErrorResponse'
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:
    TopUp:
      properties:
        topUpId:
          type: string
          format: uuid
        productKey:
          type: string
          examples: [MUSIC_10_DAYS]
        createdTs:
          type: string 
          format: date-time 
          examples: [2024-05-06T14:37:54.324Z]
        startTs:
          type: string 
          format: date-time 
          examples: [2024-05-08T03:12:23.123Z]
        endTs:
          type: string
          format: date-time
          examples: [2024-05-18T03:12:23.122Z]
    TopUpRequest:
      type: object
      required:
        - topUps
      properties:
        topUps:
          $ref: '#/components/schemas/TopUpsArray'
    TopUpsArray:
      type: array 
      items:
        $ref: '#/components/schemas/TopUpRequestItem'
    TopUpRequestItem:
      type: object
      required:
        - productKey
      properties:
        productKey:
          type: string
          examples: [MUSIC_10_DAYS]
    TopUpResponse:
      type: object
      properties:
        entitlementId:
          type: string
          format: uuid 
        topUpsExpiry:
          $ref: '#/components/schemas/TopUpsExpiry'
        topUps:
          type: array 
          items:
            $ref: '#/components/schemas/TopUp'
    TopUpsExpiry:
      type: object
      properties:
        ts:
          type: string
          format: date-time
          examples: [2024-05-18T03:12:23.122Z]
        behavior:
          type: string
          enum: [SUSPEND, TERMINATE_IMMEDIATE]
    BangoErrorResponse:
      required:
        - responseMessage
      properties:
        responseMessage:
          type: string
          examples: [Variable error message providing more information about what went wrong]
        metadata:
          $ref: '#/components/schemas/ErrorMetadata'
    ErrorMetadata:
      properties:
        responseMessageFrom:
          type: string
          examples: [BANGO]
    
    EchoResponse:
      type: object
      properties:
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
        echo:
          type: string
          examples: ["{echoString}"]
    EntitlementRequest:
      type: object
      required:
        - customerIdentifier
        - merchantAccountKey
        - productKey
        - notificationUrl
      properties:
        customerIdentifier:
          type: string
          description: Unique, immutable user identifier 
          examples: ["123456789"]
        merchantAccountKey:
          type: string
          description: Unique identifier for the content provider
          examples: [BANGO_US]
        productKey:
          type: string
          description: Unique identifier for the product/offer
          examples: [MUSIC]
        notificationUrl:
          type: string
          format: url
          description: The endpoint where Bango will send all notifications regarding this entitlement
          examples: [https://notifications.bango.com]
        offerKey:
          type: string
          description: Entitlement offer identifier
          examples: [BUNDLE]
        externalEntitlementId:
          type: string
          description: Unique identifier for the entitlement provided by the reseller. If the previous attempt to create an entitlement failed, this value can be reused.
          examples: [124130d2-2cbc-45a1-ab9b-dfa8b67a2e63]
        entitlementDisplayName:
          type: string
          description: Entitlement display name, seen in reports.
          examples: [30 day free trial for Bango Music]
        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]
        extensionData:
          type: object
          $ref: '#/components/schemas/ExtensionData'
        extraInformation:
          type: object
          $ref: '#/components/schemas/ExtraInformation'
    ExtensionData:
      type: object
      description: Custom key value pairs
      properties:
        customField1:
          type: string
          examples: [value1]
        customField2:
          type: string
          examples: [value2]
    ExtraInformation:
      type: object
      properties:
        communicationInformation:
          $ref: '#/components/schemas/CommunicationInformation'
        clientDevice:
          $ref: '#/components/schemas/ClientDevice'
        source:
          $ref: '#/components/schemas/Source'
    CommunicationInformation:
      type: object
      properties:
        msisdn:
         type: string
         examples: ["441234567890"]
        emailAddress:
          type: string
          examples: [example@bango.com]
    ClientDevice:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum: [STB, MOBILE, DESKTOP, TABLET]
          description: The type of device. This field is mandatory if clientDevice is being provided
          examples: [STB]
        id:
          type: string
          description: The unique id of the device
          examples: [bc449c9e-406f-4399-a3ff-8671a27ac410]
        typeId:
          type: string
          description: The common id for the type of device
          examples: [P49AJFND8NFN23NANGAJG]
        modelName:
          type: string
          description: The model name of the device
          examples: [STB Model X7]
        modelNumber:
          type: string
          description: The model number of the device
          examples: [IAH45IAOF/5]
        serialNumber:
          type: string
          description: The serial number of the device
          examples: [JHFJHA43JNFA9393GFD]
        osType:
          type: string
          description: The operating system of the device
          examples: [Linux]
        osVersion:
          type: string
          description: The version of the operating system of the device
          examples: [10.3.8]
        macAddress:
          type: string
          description: The MAC address of the device
          examples: [4A-0F-99-F2-D3-DD]
        browser:
          type: string
          description: The browser being used
          examples: [Chrome]
    Source:
      type: object
      properties:
        channelType:
          type: string 
          enum: [Retail, SMS, App, Website, Email, Call Centre, Mobile, Set Top Box, Other]
          description: The channel the customer used to get the offer
          examples: [Retail]
        campaignRef:
          type: string
          description: The reference of the campaign that attracted the customer
          examples: [SUMMER_PROMO]
        referrer:
          type: string
          description: The origin of the customer's request
          examples: [SEARCH_ENGINE]
        bundleId:
          type: string
          description: Identifies the bundle the entitlement is part of
          examples: [BundleABC123]
        country:
          type: string 
          description: The customer's country
          examples: [United Kingdom]
        region:
          type: string
          description: The customer's regional area or code
          examples: [CB1 3ED]
        brand:
          type: string
          description: The brand 
          examples: [BrandA]
    CreateEntitlementResponse:
      type: object
      properties:
        entitlementId:
          type: string
          description: Unique identifier representing a specific entitlement
        customerIdentifier:
          type: string
          description: Unique, immutable user identifier 
          examples: ["123456789"]
        sharedCustomerId:
          type: string
          format: uuid
          description: Bango generated id shared between reseller and merchant for this customer (contact support for setup) 
          examples: [db2001b5-fde5-4654-9ecd-b3b04ba8f025]
        merchantAccountKey:
          type: string
          description: Unique identifier for the content provider
          examples: [BANGO_US]
        productKey:
          type: string
          description: Unique identifier for the product/offer
          examples: [MUSIC]
        notificationUrl:
          type: string
          format: url
          description: The endpoint where Bango will send all notifications regarding this entitlement
          examples: [https://notifications.bango.com]
        offerKey:
          type: string
          description: Entitlement offer identifier
          examples: [BUNDLE]
        externalEntitlementId:
          type: string
          description: Unique identifier for the entitlement provided by the reseller. If the previous attempt to create an entitlement failed, this value can be reused.
          examples: [124130d2-2cbc-45a1-ab9b-dfa8b67a2e63]
        entitlementDisplayName:
          type: string
          description: Entitlement display name used in reports.
          examples: [30 day free trial for Bango Music]
        dateCreated:
          type: string
          format: date
          description: Timestamp for the creation of the entitlement
          examples: [2024-06-22T17:35:38.92Z]
        dateActivated:
          type: string
          format: Date
          description: Timestamp provided by the content provider when the entitlement is activated
          examples: [0001-01-01T00:00:00Z]
        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]

        parameters:
          type: object
          properties:
            Action:
              type: string
              description: The action the reseller should take next
              enum: [NAVIGATE_TO_URL]
            Url:
              type: string
              description: The activation url provided by the content provider. Redirect the customer to this link to continue the activation process.
              examples: [https://activation-link.bango.com]

    EntitlementResponse:
      type: object
      properties:
        entitlementId:
          type: string
          description: Unique identifier representing a specific entitlement
        customerIdentifier:
          type: string
          description: Unique, immutable user identifier 
          examples: ["123456789"]
        sharedCustomerId:
          type: string
          format: uuid
          description: Bango generated id shared between reseller and merchant for this customer (contact support for setup) 
          examples: [db2001b5-fde5-4654-9ecd-b3b04ba8f025]
        merchantAccountKey:
          type: string
          description: Unique identifier for the content provider
          examples: [BANGO_US]
        productKey:
          type: string
          description: Unique identifier for the product/offer
          examples: [MUSIC]
        notificationUrl:
          type: string
          format: url
          description: The endpoint where Bango will send all notifications regarding this entitlement
          examples: [https://notifications.bango.com]
        offerKey:
          type: string
          description: Entitlement offer identifier
          examples: [BUNDLE]
        externalEntitlementId:
          type: string
          description: Unique identifier for the entitlement provided by the reseller. If the previous attempt to create an entitlement failed, this value can be reused.
          examples: [124130d2-2cbc-45a1-ab9b-dfa8b67a2e63]
        entitlementDisplayName:
          type: string
          description: Entitlement display name used in reports.
          examples: [30 day free trial for Bango Music]
        dateCreated:
          type: string
          format: date
          description: Timestamp for the creation of the entitlement
          examples: [2024-06-22T17:35:38.92Z]
        dateActivated:
          type: string
          format: Date
          description: Timestamp provided by the content provider when the entitlement is activated
          examples: [2024-06-23T17:35:38.92Z]
        dateEnded:
          type: string
          format: date
          description: Timestamp for when the entitlement terminated
          examples: [0001-01-01T00:00:00Z]
        dateSuspended:
          type: string
          format: date
          description: Timestamp for when the entitlement was suspended
          examples: [null]
        dateResumed:
          type: string
          format: date
          description: Timestamp for when the entitlement was last resumed
          examples: [null]
        dateExpiry:
          type: string
          format: date
          description: If set, Bango will schedule a termination request to the content provider on this date. Date format must be ISO 8601
          examples: [2024-12-05T07:46:52Z]
        dateAutoSuspend:
          type: string
          format: date
          description: If set, Bango will schedule a suspension request to the content provider on this date. Date format must be ISO 8601
          examples: [2024-09-05T07:46:52Z]
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
        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. 
        activationCode:
          type: string
          description: Code or token used for the entitlement activation
          examples: [null]
        parameters:
          type: object
          properties:
            Action:
              type: string
              description: The action the reseller should take next
              enum: [NAVIGATE_TO_URL]
            Url:
              type: string
              description: The activation url provided by the content provider. Redirect the customer to this link to continue the activation process.
              examples: [https://activation-link.bango.com]
        extensionData:
          type: object
          $ref: '#/components/schemas/ExtensionData'
        extraInformation:
          type: object
          $ref: '#/components/schemas/ExtraInformation'
    ActivationInfo:
      type: object
      properties:
        options:
          type: string
          format: array
          enum: [SHORT_LIVED_TOKEN, LONG_LIVED_TOKEN]
          description: Optional properties for the type of activation token being requested.
          examples: [SHORT_LIVED_TOKEN]
    ActivationInfoResponse:
      type: object
      required:
      - entitlementId
      - responseCode
      - responseMessage
      properties:
        entitlementId:
          type: string
          description: Unique identifier representing a specific entitlement.
          examples: [a25100b8-4e0c-4e37-b921-cac9cb1e930f]
        responseCode:
          type: string
          examples: [CLIENT_ACTIION_REQUIRED]
        responseMessage:
          type: string
          examples: [An action is required to be performed by the client.]
        activationCode:
          type: string
          description: The activation response will normally be a url. However, this field is returned instead of the parameters block if the content provider supports activation codes rather than urls
          examples: [STB45454]
        parameters:
          type: object
          properties:
            action:
              type: string
              enum: [NAVIGATE_TO_URL]
              description: The action the reseller should take next
              examples: [NAVIGATE_TO_URL]
            url: 
              type: string
              description: The url that the reseller must redirect the user to when the `NAVIGATE_TO_URL` action is provided
              examples: [https://activate.bango.com/?entitlementId=a25100b8-4e0c-4e37-b921-cac9cb1e930f]
            urlExpiry:
              type: string
              format: date
              description: Timestamp for when the activation information will expire (if provided by the content provider). Date is in UTC ISO 8601 format 
              examples: [2024-12-01T00:00:00Z]
    EntitlementUpdate:
      type: object
      required:
        - entitlementId
      properties:
        entitlementId:
          type: string
          description: Unique identifier representing a specific entitlement
          examples: [a25100b8-4e0c-4e37-b921-cac9cb1e930f]
        customerIdentifier:
          type: string
          description: User unique identifier
          examples: ["4407123456789"]
        productKey:
          type: string
          description: Entitlement product unique identifier
          examples: [MUSIC]
        entitlementDisplayName:
          type: string
          description: Entitlement display name. For example, "30 days Bango music"
          examples: [30 days of Bango music]
        offerKey:
          type: string
          description: 'Entitlement offer. For example, "BUNDLE" (optional).'
          examples: [BUNDLEA]
        dateExpiry:
          type: string
          format: date
          description: Entitlement expiry date in UTC ISO 8601 format. Null if no expiry
            (yyyy-MM-ddThh:mm:ssZ)
          examples: []
        dateAutoSuspend:
          type: string
          format: date
          description: Entitlement auto-suspension date in UTC ISO 8601 format. Null if no auto-suspension
          examples: []
        notificationUrl:
          type: string
          format: url
          description: The (POST) endpoint where all entitlement lifecycle notifications will be sent
          examples: ["https://notifications.bango.com"]
        externalEntitlementId:
          type: string
          description: Unique identifier for the entitlement provided by the Reseller. If the previous attempt to create an entitlement failed, the externalEntitlementId can be reused in a new create request.
          examples: [124130d2-2cbc-45a1-ab9b-dfa8b67a2e63]
        extensionData:
          type: object
          $ref: '#/components/schemas/ExtensionData'
        extraInformation:
          type: object
          $ref: '#/components/schemas/ExtraInformation'
    EntitlementReport:
      type: object
      required:
        - customerIdentifier
      properties:
        customerIdentifier:
          type: string
          description: Unique customer identifier
          examples: ["4407123456789"]
        productKey:
          type: string
          description: Entitlement product unique identifier
          examples: [MUSIC]
        status:
          type: string
          enum: [PENDING, ACTIVE, SUSPENDED, CANCELLED, REVOKED]
          description: Entitlement status
          examples: [ACTIVE]
    EntitlementTerminate:
      type: object
      description: Reason category, code and description are added to the extensionData after a successful request to terminate the entitlement
      properties:
        cancelReasonCategory:
          type: string
          enum: [CUSTOMER_CANCELLED, REVOKED]
          description: High level category for the type of termination. 
        cancelReasonCode:
          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/"
        cancelReasonDescription:
          type: string
          description: Additional information for termination reason
    EntitlementReportResponse:
      type: object
      properties:
        responseCode:
          type: string
          examples: [OK]
        responseMessage:
          type: string
          examples: [Success]
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/EntitlementResponse'
    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

    ErrorResponseObject:
          type: object
          properties:
            responseCode:
              type: string
            responseMessage:
              type: string
            metadata:
              $ref: '#/components/schemas/Metadata'
    Metadata:
      type: object
      properties:
        responseMessageFrom:
          type: string
          description: 
            The originator of the error (either Bango or the content provider)
          enum:
            - BANGO
            - MERCHANT
    
    ResumeRequest:
      type: object
      properties:
        productKey:
          type: string
          description: Entitlement product unique identifier
          examples: [MUSIC]
    
    AccountRecoveryResponse:
      title: AccountRecoveryResponse
      required:
        - accountRecoveryType
      type: object
      properties:
        responseCode:
          title: Responsecode
          type: string
          default: Ok
        responseMessage:
          title: Responsemessage
          type: string
          default: Success
        recoveryUrl:
          title: recoveryUrl
          type: string
          default: https://bango.com/activate
        expiryTs:
          title: expiryTs
          type: string
          default: '2024-06-17T20:38:39Z'
      description: Successful Response
    AC-AuthorizationErrorResponse:
      title: AuthorizationErrorResponse
      type: object
      properties:
        responseCode:
          title: Responsecode
          type: string
          default: UNAUTHORIZED
        responseMessage:
          title: Responsemessage
          type: string
          default: You have not provided adequate credentials to access this resource.
      description: Response model for HTTP status code 401.
    AC-BadRequestResponse:
      title: BadRequestResponse
      type: object
      properties:
        responseCode:
          title: Responsecode
          type: string
          default: BAD_REQUEST
        responseMessage:
          title: Responsemessage
          type: string
          default: Invalid request.
      description: Response model for HTTP status code 400.
    EntitlementAccountRecoveryRequest:
      title: EntitlementAccountRecoveryRequest
      required:
        - resellerKey
        - requestType
      type: object
      properties:
        resellerKey:
          title: Resellerkey
          type: string
          description: Static value representing the reseller on the Bango system
          examples: [BANGO_TEL]
        requestType:
          type: string
          enum: [ACCOUNT_RECOVERY, ACCOUNT_UNLINK]
          description: The type of account recovery required
          examples: [ACCOUNT_RECOVERY]


    AC-InternalErrorResponse:
      type: object
      properties:
        responseCode:
          title: Responsecode
          type: string
          default: INTERNAL_ERROR
        responseMessage:
          title: Responsemessage
          type: string
          examples: [The server encountered an unexpected condition which prevented it from fulfilling the request.]
    AC-NotFoundResponse:
      type: object
      properties:
        responseCode:
          title: Responsecode
          type: string
          examples: [NOT_FOUND]
        responseMessage:
          title: Responsemessage
          type: string
          examples: [Resource not found]
    AC-InvalidStateResponse:
      type: object
      properties:
        responseCode:
          title: Responsecode
          type: string
          default: INVALID_STATE
        responseMessage:
          title: Responsemessage
          type: string
          examples: [The entitlement is not in the correct state to be recovered.]
    AC-TooManyRequestsResponse:
      type: object
      properties:
        responseCode:
          title: Responsecode
          type: string
          default: TOO_MANY_REQUESTS
        responseMessage:
          title: Responsemessage
          type: string
          examples: [Request limit has been reached, please retry.]
    AC-ServiceUnavailableResponse:
      type: object
      properties:
        responseCode:
          title: Responsecode
          type: string
          default: SERVICE_UNAVAILABLE
        responseMessage:
          title: Responsemessage
          type: string
          examples: [null]