openapi: 3.1.0
info:
  title: Consumer offers
  version: 1.0.0
  description: "# Overview\nA consumer offer is the consumer's instance of an offer\
    \ from the offer catalog.\n\nThe consumer offer API is responsible for orchestrating\
    \ the creation of all components needed based on the offer configuration. This\
    \ includes one or more entitlements (based on the product tier information assocated\
    \ to the offer) and a billing plan (based on the offer's plan) Once started, the\
    \ billing plan drives the lifecycle management for the consumer's offer.\n\nThe\
    \ consumer offer API also enables you to retrieve consumer offers details in 2\
    \ ways:\n\n- Get by consumerOfferId (returns 1 consumer offer)\n- Search by consumerIdentifier\
    \ (returns an array of consumer offers)\n\nIt also enables you to immediately\
    \ terminate the consumer offer. This request will orchestrate the immediate end\
    \ of all linked entitlements and the billing plan.\n\n# Change log\n**2025-07-14**\
    \ | v.1.0.0\n- It is now possible to optionally include the following information:\n\
    \    - `msisdn` and `emailAddress` information for the consumer\n    - `source`\
    \ information\n- Addition of `sharedCustomerId` for each entitlement in the response\n\
    - Examples for create request variations have been added\n- Moved to major version\
    \ to align with major.minor.fix \n\n**2025-05-27** | v.0.0.3\n- Specification\
    \ aligned to expected api behaviour\n\n**2025-02-17** | v.0.0.2\n- A consumerOffer\
    \ can now include an optional paymentInstrumentToken\n\n**2024-09-30** | v.0.0.1\n\
    - This is the public api for consumer offers\n"
servers:
- url: https://api.sandbox.bango.com
  description: Integration test environment
- url: https://api.bango.com
  description: Production environment
security:
- basic: []
paths:
  /consumerOffers:
    post:
      summary: Create Consumer Offer
      description: Use this operation to create consumer offer. The extended request
        shows all optional fields available.
      operationId: CreateConsumerOfferOApi-fm
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConsumerOfferOApi-FmInput'
            examples:
              Basic request - redemption:
                value:
                  consumer:
                    consumerIdentifier: bob1234
                  offer:
                    offerId: ce124847-08c4-4e0e-b917-9d5ef1240a69
              Extended request - including all optional fields available:
                value:
                  consumer:
                    consumerIdentifier: bob1234
                    communicationInformation:
                      emailAddress: bob@company.com
                      msisdn: '+44123456789'
                  offer:
                    offerId: ce124847-08c4-4e0e-b917-9d5ef1240a69
                  source:
                    channelType: Retail
                    bundleId: externalRef
                    brand: ABC
                    country: UK
                    region: Cambridgeshire
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelResponseForCreate'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 400
                message: namespaceId is invalid
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 404
                message: could not find bango user
        '408':
          description: Request Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 408
                message: Request timeout
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 409
                message: Only one product is allowed in the Offer
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 422
                message: Maximum number of entitlements for user reached
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 500
                message: Internal Server Error
  /consumerOffers/{consumerOfferId}:
    get:
      summary: Get Consumer Offer
      description: use this operation to get consumer offer
      operationId: GetConsumerOfferOApi-fm
      parameters:
      - name: consumerOfferId
        in: path
        description: id of the consumer offer
        required: true
        schema:
          type: string
          description: id of the consumer offer
          format: uuid
      - name: awaitStatus
        in: query
        description: "* FULLY_CREATED: all entitlements have been created \n\r* FULLY_ACTIVE:\
          \ all entitlements are active\n\r* FULLY_TERMINATED: all entitlements have\
          \ been terminated"
        schema:
          type: string
          description: "* FULLY_CREATED: all fully created \n\r* FULLY_ACTIVE: all\
            \ fully active\n\r* FULLY_TERMINATED: all fully terminated"
          enum:
          - FULLY_CREATED
          - FULLY_ACTIVE
          - FULLY_TERMINATED
      - name: timeout
        in: query
        description: how long you wish to wait for the response  in ISO 8601 duration
          format, between 1 and 10 seconds e.g. PT10S
        schema:
          type: string
          description: how long you wish to wait for the response
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 400
                message: namespaceId is invalid
        '401':
          description: Unauthorized (no response body returned)
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 500
                message: Internal server error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 404
                message: Not Found
  /consumerOffers/{consumerOfferId}/terminate:
    post:
      summary: Terminate Consumer Offer
      description: use this operation to terminate a consumer offer
      operationId: TerminateConsumerOfferOApi-fm
      parameters:
      - name: consumerOfferId
        in: path
        description: consumer offer id
        required: true
        schema:
          type: string
          description: consumer offer id
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminateConsumerOfferOApi-FmInput'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 400
                message: namespaceId is invalid
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 404
                message: not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 409
                message: Consumer offer was already terminated
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 500
                message: Internal server error
  /consumerOffers/search:
    post:
      summary: Search Consumer Offers
      description: use this operation to search consumer offers
      operationId: SearchConsumerOfferOApi-fm
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchConsumerOfferOApi-FmInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ModelResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 400
                message: namespaceId is invalid
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 404
                message: not found
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 500
                message: Internal server error
components:
  schemas:
    CreateConsumerOfferOApi-FmInput:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/ModelConsumer'
        offer:
          $ref: '#/components/schemas/ModelOfferRequest'
        source:
          $ref: '#/components/schemas/ModelSource'
      required:
      - consumer
      - offer
    ModelActivation:
      type: object
      properties:
        activationCode:
          type: string
          description: merchants activation code
        activationUrl:
          type: string
          description: merchants activation url
        activationUrlExpiryTs:
          type: string
          description: expiry time of activation url
          format: date-time
    ModelConsumerOffer:
      type: object
      properties:
        consumerOfferId:
          type: string
          description: identifier for the consumer offer
          format: uuid
        offerId:
          type: string
          description: offer identifier
          format: uuid
        consumer:
          $ref: '#/components/schemas/ModelConsumer'
        status:
          $ref: '#/components/schemas/ModelConsumerOfferStatus'
        subStatus:
          $ref: '#/components/schemas/ModelConsumerOfferSubStatus'
        timeline:
          $ref: '#/components/schemas/ModelConsumerOfferTimeline'
    ModelConsumerOfferStatus:
      type: string
      description: current consumer offer status
      enum:
      - REQUESTED
      - CREATES_FAILED
      - FULLY_CREATED
      - PARTIALLY_CREATED
      - FULLY_ACTIVE
      - FULLY_TERMINATED
    ModelConsumerOfferSubStatus:
      type: string
      description: current consumer offer sub-status
      enum:
      - PENDING_CREATES
      - PENDING_ACTIVATES
      - PENDING_TERMINATES
    ModelConsumerOfferForCreate:
      type: object
      properties:
        consumerOfferId:
          type: string
          description: identifier for the consumer offer
          format: uuid
        offerId:
          type: string
          description: offer identifier
          format: uuid
        consumer:
          $ref: '#/components/schemas/ModelConsumer'
        status:
          $ref: '#/components/schemas/ModelConsumerOfferStatus'
        subStatus:
          $ref: '#/components/schemas/ModelConsumerOfferSubStatus'
        timeline:
          $ref: '#/components/schemas/ModelConsumerOfferTimelineForCreate'
    ModelConsumerOfferTimeline:
      type: object
      properties:
        createRequestedTs:
          type: string
          description: date creation of the offer was requested
          format: date-time
        createdTs:
          type: string
          description: date the offer was created
          format: date-time
        createsFailedTs:
          type: string
          description: date the offer failed to be created
          format: date-time
        entitlementsRequestedTs:
          type: string
          description: date the entitlements for the offer were requested
          format: date-time
        terminateRequestedTs:
          type: string
          description: date the entitlements for the offer were terminated
          format: date-time
      description: timeline of changes made to the consumer offer
    ModelConsumerOfferTimelineForCreate:
      type: object
      properties:
        createRequestedTs:
          type: string
          description: date creation of the offer was requested
          format: date-time
      description: timeline of changes made to the consumer offer
    ModelConsumer:
      type: object
      properties:
        consumerIdentifier:
          type: string
          description: identity of the consumer
          maxLength: 400
        communicationInformation:
          $ref: '#/components/schemas/ModelCommunicationInformation'
      description: the consumer request body
      required:
      - consumerIdentifier
    ModelCommunicationInformation:
      type: object
      properties:
        emailAddress:
          type: string
          description: Consumer's email
        msisdn:
          type: string
          description: Consumer's msisdn
    ModelSource:
      type: object
      properties:
        channelType:
          type: string
          enum:
          - Retail
          - SMS
          - App
          - Website
          - Email
          - Call Centre
          - Mobile
          - Set Top Box
          - Other
          description: The channel the consumer used to get the offer
        bundleId:
          type: string
          description: Identifies the reseller's bundle
        brand:
          type: string
          description: The reseller's brand
        country:
          type: string
          description: The consumer's country
        region:
          type: string
          description: The consumer's regional area or code
    ModelPaymentMethodRequest:
      type: object
      properties:
        paymentInstrumentToken:
          type: string
          description: uuid represents a payment instrument token
          format: uuid
      description: the payment request body
      required:
      - paymentInstrumentToken
    ModelEntitlement:
      type: object
      properties:
        activation:
          $ref: '#/components/schemas/ModelActivation'
        entitlementId:
          type: string
          description: uuid represents a unique identifier for this entitlement
          format: uuid
        merchantAccountKey:
          type: string
          description: merchants account key
        productKey:
          type: string
          description: resellers product key
        status:
          $ref: '#/components/schemas/ModelEntitlementStatus'
        subStatus:
          $ref: '#/components/schemas/ModelEntitlementSubStatus'
        sharedCustomerId:
          type: string
          description: auto-generated unique consumer id for this content provider
          format: uuid
        timeline:
          $ref: '#/components/schemas/ModelEntitlementTimeline'
        source:
          $ref: '#/components/schemas/ModelSource'
    ModelEntitlementStatus:
      type: string
      description: current entitlement status
      enum:
      - REQUESTED
      - CREATED
      - ACTIVE
      - CREATE_FAILED
      - ENDED
      - SUSPENDED
    ModelEntitlementSubStatus:
      type: string
      description: current entitlement sub-status
      enum:
      - PENDING_CREATE
      - PENDING_ACTIVATE
      - ENDING
      - IMMEDIATE
    ModelEntitlementForCreate:
      type: object
      properties:
        entitlementId:
          type: string
          description: uuid represents a unique identifier for this entitlement
          format: uuid
        merchantAccountKey:
          type: string
          description: merchants account key
        productKey:
          type: string
          description: resellers product key
        status:
          $ref: '#/components/schemas/ModelEntitlementStatus'
        subStatus:
          $ref: '#/components/schemas/ModelEntitlementSubStatus'
        sharedCustomerId:
          type: string
          description: auto-generated unique consumer id for this content provider
          format: uuid
        timeline:
          $ref: '#/components/schemas/ModelEntitlementTimelineForCreate'
        source:
          $ref: '#/components/schemas/ModelSource'
    ModelEntitlementTimeline:
      type: object
      properties:
        activatedTs:
          type: string
          format: date-time
        createFailedTs:
          type: string
          format: date-time
        createRequestedTs:
          type: string
          format: date-time
        createdTs:
          type: string
          format: date-time
        terminatedTs:
          type: string
          format: date-time
    ModelEntitlementTimelineForCreate:
      type: object
      properties:
        createRequestedTs:
          type: string
          format: date-time
    ModelOfferRequest:
      type: object
      properties:
        offerId:
          type: string
          description: id of the offer
      description: the offer request body
      required:
      - offerId
    ModelResponse:
      type: object
      properties:
        consumerOffer:
          $ref: '#/components/schemas/ModelConsumerOffer'
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/ModelEntitlement'
    ModelResponseForCreate:
      type: object
      properties:
        consumerOffer:
          $ref: '#/components/schemas/ModelConsumerOfferForCreate'
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/ModelEntitlementForCreate'
    ModelsDefaultErrorResponseModel:
      type: object
      properties:
        Message:
          type: string
          description: description of the error
        StatusCode:
          type: integer
          description: error status code
          format: int32
    SearchConsumerOfferOApi-FmInput:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/ModelConsumerSearch'
        status:
          type: string
          enum:
          - FULLY_CREATED
          - FULLY_ACTIVE
          - FULLY_TERMINATED
      required:
      - consumer
    ModelConsumerSearch:
      type: object
      properties:
        consumerIdentifier:
          type: string
          description: identity of the consumer
          maxLength: 400
      description: the consumer search request body
      required:
      - consumerIdentifier
    TerminateConsumerOfferOApi-FmInput:
      type: object
      properties:
        reasonDescription:
          type: string
          description: reason for termination
          maxLength: 500
  securitySchemes:
    basic:
      type: http
      description: Basic authentication
      scheme: basic
