openapi: 3.1.0
x-stoplight:
  id: mnzah38ri1jks
info:
  title: consumer-offers-api
  version: 0.0.3
  description: |
    # Overview
    A consumer offer is the consumer's instance of an offer from the offer catalog.

    The 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.

    The consumer offer API also enables you to retrieve consumer offers details in 2 ways:
    
    - Get by consumerOfferId (returns 1 consumer offer)
    - Search by consumerIdentifier (returns an array of consumer offers)

    It also enables you to immediately terminate the consumer offer. This request will orchestrate the immediate end of all linked entitlements and the billing plan.

    # Change log
    **2025-05-27** | v.0.0.3
    - Specification aligned to expected api behaviour

    **2025-02-17** | v.0.0.2
    - A consumerOffer can now include an optional paymentInstrumentToken
    
    **2024-09-30** | v.0.0.1
    - This is the public api for consumer offers
servers:
  - url: 'https://api.sandbox.bango.com'
paths:
  /consumerOffers:
    post:
      summary: Create Consumer Offer
      description: use this operation to create consumer offer
      operationId: CreateConsumerOfferOApi-fm
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConsumerOfferOApi-FmInput'
      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 fully created \n\r* FULLY_ACTIVE: all fully active\n\r* FULLY_TERMINATED: all fully 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
          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/ModelConsumerRequest'
        offer:
          $ref: '#/components/schemas/ModelOfferRequest'
        paymentMethod:
          $ref: '#/components/schemas/ModelPaymentMethodRequest'
      required:
        - consumer
        - offer
      x-stoplight:
        id: h92u8349xbdal
    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
          nullable: true
      x-stoplight:
        id: j5rg5gkkwq9oj
    ModelConsumerOffer:
      type: object
      properties:
        consumerOfferId:
          type: string
          description: identifier for the consumer offer
          format: uuid
        offerId:
          type: string
          description: offer identifier
          format: uuid
        status:
          $ref: '#/components/schemas/ModelConsumerOfferStatus'
        subStatus:
          $ref: '#/components/schemas/ModelConsumerOfferSubStatus'
        timeline:
          $ref: '#/components/schemas/ModelConsumerOfferTimeline'
      x-stoplight:
        id: vtz3jikan1t4p
    ModelConsumerOfferStatus:
      type: string
      description: current consumer offer status
      enum:
        - REQUESTED
        - CREATES_FAILED
        - FULLY_CREATED
        - PARTIALLY_CREATED
        - FULLY_ACTIVE
        - FULLY_TERMINATED
      x-stoplight:
        id: 08d1r7fw37caj
    ModelConsumerOfferSubStatus:
      type: string
      description: current consumer offer sub-status
      enum:
        - PENDING_CREATES
        - PENDING_ACTIVATES
        - PENDING_TERMINATES
      x-stoplight:
        id: 6i3pnwtyn01g2
    ModelConsumerOfferForCreate:
      type: object
      properties:
        consumerOfferId:
          type: string
          description: identifier for the consumer offer
          format: uuid
        offerId:
          type: string
          description: offer identifier
          format: uuid
        status:
          $ref: '#/components/schemas/ModelConsumerOfferStatus'
        subStatus:
          $ref: '#/components/schemas/ModelConsumerOfferSubStatus'
        timeline:
          $ref: '#/components/schemas/ModelConsumerOfferTimelineForCreate'
      x-stoplight:
        id: k9wdlzcjva9ug
    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
          nullable: true
        createsFailedTs:
          type: string
          description: date the offer failed to be created
          format: date-time
          nullable: true
        entitlementsRequestedTs:
          type: string
          description: date the entitlements for the offer were requested
          format: date-time
          nullable: true
        terminateRequestedTs:
          type: string
          description: date the entitlements for the offer were terminated
          format: date-time
          nullable: true
      description: timeline of changes made to the consumer offer
      x-stoplight:
        id: gxd1xoelfc4ml
    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
      x-stoplight:
        id: c72wxy6m3mzxq
    ModelConsumerRequest:
      type: object
      properties:
        consumerIdentifier:
          type: string
          description: identity of the consumer
          maxLength: 400
      description: the consumer request body
      required:
        - consumerIdentifier
      x-stoplight:
        id: ie2c7h2803vq7
    ModelPaymentMethodRequest:
      type: object
      x-stoplight:
        id: ukrgtsvvazblg
      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'
        timeline:
          $ref: '#/components/schemas/ModelEntitlementTimeline'
      x-stoplight:
        id: ocvvvzu0cvo87
    ModelEntitlementStatus:
      type: string
      description: current entitlement status
      enum:
        - REQUESTED
        - CREATED
        - ACTIVE
        - CREATE_FAILED
        - ENDED
        - SUSPENDED
      x-stoplight:
        id: bn9gtm7pf903n
    ModelEntitlementSubStatus:
      type: string
      description: current entitlement sub-status
      enum:
        - PENDING_CREATE
        - PENDING_ACTIVATE
        - ENDING
        - IMMEDIATE
      x-stoplight:
        id: uhcc7jepwffu0
    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'
        timeline:
          $ref: '#/components/schemas/ModelEntitlementTimelineForCreate'
      x-stoplight:
        id: kxmbstdz4j9nb
    ModelEntitlementTimeline:
      type: object
      properties:
        activatedTs:
          type: string
          format: date-time
          nullable: true
        createFailedTs:
          type: string
          format: date-time
          nullable: true
        createRequestedTs:
          type: string
          format: date-time
        createdTs:
          type: string
          format: date-time
          nullable: true
        terminatedTs:
          type: string
          format: date-time
          nullable: true
      x-stoplight:
        id: 6f3f80z6skmrz
    ModelEntitlementTimelineForCreate:
      type: object
      properties:
        createRequestedTs:
          type: string
          format: date-time
      x-stoplight:
        id: t0fcbwwcm65jn
    ModelOfferRequest:
      type: object
      properties:
        offerId:
          type: string
          description: id of the offer
      description: the offer request body
      required:
        - offerId
      x-stoplight:
        id: 8zdeystz56szw
    ModelResponse:
      type: object
      properties:
        consumerOffer:
          $ref: '#/components/schemas/ModelConsumerOffer'
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/ModelEntitlement'
      x-stoplight:
        id: dlmsulznx3dn7
    ModelResponseForCreate:
      type: object
      properties:
        consumerOffer:
          $ref: '#/components/schemas/ModelConsumerOfferForCreate'
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/ModelEntitlementForCreate'
      x-stoplight:
        id: pva6h11pjh13k
    ModelsDefaultErrorResponseModel:
      type: object
      properties:
        Message:
          type: string
          description: description of the error
        StatusCode:
          type: integer
          description: error status code
          format: int32
      x-stoplight:
        id: 0kwigcwlb2bzy
    SearchConsumerOfferOApi-FmInput:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/ModelConsumerRequest'
        status:
          type: string
          enum:
            - FULLY_CREATED
            - FULLY_ACTIVE
            - FULLY_TERMINATED
      required:
        - consumer
      x-stoplight:
        id: 9d8eq33cxamta
    TerminateConsumerOfferOApi-FmInput:
      type: object
      properties:
        reasonDescription:
          type: string
          description: reason for termination
          maxLength: 500
      x-stoplight:
        id: te77vow7s5ivb
  securitySchemes:
    http:
      type: http
      scheme: basic
      description: Basic Authorization