openapi: 3.0.1
x-stoplight:
  id: fs4h4pj4kafh8
info:
  title: consumer-offers-api
  version: 0.0.2
  description: |
    # Change log
    **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
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 404
                message: could not find bango user
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 409
                message: Only one product is allowed in the Offer
  '/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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsDefaultErrorResponseModel'
              example:
                statusCode: 500
                message: Failed to get consumer offer
  '/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
        '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: an internal error occurred
  /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
        '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
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: btpnoeu50tri2
    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: 4c1klw46ozljj
    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: e6mi8jj67xaq6
    ModelConsumerOfferStatus:
      type: string
      description: current consumer offer status
      enum:
        - REQUESTED
        - CREATES_FAILED
        - FULLY_CREATED
        - PARTIALLY_CREATED
        - FULLY_ACTIVE
        - FULLY_TERMINATED
      x-stoplight:
        id: 3dikot1waa6c0
    ModelConsumerOfferSubStatus:
      type: string
      description: current consumer offer sub-status
      enum:
        - PENDING_CREATES
        - PENDING_ACTIVATES
        - PENDING_TERMINATES
      x-stoplight:
        id: v3psek8upm2df
    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: 5sq1rpvm1sf0w
    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: 4fo6try7kwdu4
    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: 1evbpiqm9us4q
    ModelConsumerRequest:
      type: object
      properties:
        consumerIdentifier:
          type: string
          description: identity of the consumer
          maxLength: 400
      description: the consumer request body
      required:
        - consumerIdentifier
      x-stoplight:
        id: fh28n1tby1igm
    ModelPaymentMethodRequest:
      type: object
      x-stoplight:
        id: f2a63b83cc0d0
      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: xy5mp9pmtf8zq
    ModelEntitlementStatus:
      type: string
      description: current consumer offer status
      enum:
        - REQUESTED
        - CREATED
        - ACTIVE
        - CREATE_FAILED
        - ENDED
        - SUSPENDED
      x-stoplight:
        id: 53l0y7l2y82nr
    ModelEntitlementSubStatus:
      type: string
      description: current consumer offer sub-status
      enum:
        - PENDING_CREATE
        - PENDING_ACTIVATE
        - ENDING
      x-stoplight:
        id: ghnwc4wlrixzw
    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: wqozaflchota4
    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: xypu34duo14br
    ModelEntitlementTimelineForCreate:
      type: object
      properties:
        createRequestedTs:
          type: string
          format: date-time
      x-stoplight:
        id: xzbctmndfkosj
    ModelOfferRequest:
      type: object
      properties:
        offerId:
          type: string
          description: id of the offer
      description: the offer request body
      required:
        - offerId
      x-stoplight:
        id: 0o0s0mi09qhch
    ModelResponse:
      type: object
      properties:
        consumerOffer:
          $ref: '#/components/schemas/ModelConsumerOffer'
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/ModelEntitlement'
      x-stoplight:
        id: 4br0as4ed90lc
    ModelResponseForCreate:
      type: object
      properties:
        consumerOffer:
          $ref: '#/components/schemas/ModelConsumerOfferForCreate'
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/ModelEntitlementForCreate'
      x-stoplight:
        id: a8bp9j9aahw1b
    ModelsDefaultErrorResponseModel:
      type: object
      properties:
        Message:
          type: string
          description: description of the error
        StatusCode:
          type: integer
          description: error status code
          format: int32
      x-stoplight:
        id: s8omstefmgyfn
    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: rsgvo57abmhi3
    TerminateConsumerOfferOApi-FmInput:
      type: object
      properties:
        reasonDescription:
          type: string
          description: reason for termination
          maxLength: 500
      x-stoplight:
        id: 0uvfe7wgkhdlb
  securitySchemes:
    http:
      type: http
      scheme: basic
      description: Basic Authorization
