openapi: 3.0.1
info:
  title: Product Ordering v1 - Canon API
  description: This service provides comprehensive product ordering capabilities for operations including order creation, management, and lifecycle operations.
    The service integrates with various product catalog systems and provides standardized
    APIs for product ordering across the MTN ecosystem.
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: '1.0'
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: "https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials"
servers:
- url: https://api.mtn.com/madapi-canonical/v1/
  description: Generated server url
security:
  - OAuth2: []
tags:
- name: Product Ordering
  description: APIs for managing product ordering operations including offer
    management, and product activation.
paths:
  /product-ordering/orders:
    post:
      tags:
      - Product Ordering
      summary: Activate Product
      description: This operation activates a new product in the product ordering
        system. The endpoint accepts a product order request with product details,
        transaction ID for tracking, and authorization claims for secure product activation.
      operationId: activateProduct
      parameters:
      - name: transactionId
        in: header
        required: true
        description: Unique id for the transaction generated by the calling channel/app
        example: one_app_98765434567976765
        schema:
          type: string
      - name: x-country-code
        in: header
        required: true
        description: Country code to know which OpCO to route the OneApp API request
          towards. To be injected by APIGEE, if needed
        example: UGA
        schema:
          type: string
      - name: x-channel-id
        in: header
        required: true
        description: Experience layer channel id of OneApp
        example: OneApp
        schema:
          type: string
          default: ''
      - name: x-authorization-claims
        in: header
        required: false
        schema:
          type: string
      - name: skipCharge
        in: header
        required: false
        schema:
          type: boolean
          default: false
          description: Placeholder to help some opcos know if subscription  is meant to be chargeless. 
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductOrderRequest'
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductOrderResp'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    note:
      type: object
      properties:
        id:
          type: string
          description: Id placeholder
        author:
          type: string
          description: Placeholder
        text:
          type: string
          description: Placeholder
    Channel:
      type: object
      properties:
        id:
          type: string
          description: Id of the channel making the purchase.
          example: MTN_ONE_APP
        role:
          type: string
          description: Role of the channel making the purchase.
        name:
          type: string
          description: Name of the channel making the purchase.
          example: MTN One App
    ItemTerm:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    ItemPrice:
      type: object
      properties:
        priceType:
          type: string
          description: Type of bundle price.
        price:
          type: object
          properties:
            taxRate:
              type: number
              example: 50.07
            taxUnit:
              type: string
              example: UGX
            dutyFreeAmount:
              type: object
              properties:
                value:
                  type: number
                  example: 30.2
                unit:
                  type: string
                  example: UGX
        priceAlteration:
          type: array
          items:
            $ref: '#/components/schemas/PriceAlteration'
    Payment:
      type: object
      properties:
        id:
          type: string
          description: Identifier for the payment method.
        name:
          type: string
          description: Name of payment method.
    Price:
      type: object
      properties:
        taxIncludedAmount:
          $ref: '#/components/schemas/TaxIncludedAmount'
    PriceAlteration:
      type: object
      properties:
        price:
          $ref: '#/components/schemas/Price'
    Product:
      type: object
      properties:
        productSpecification:
          $ref: '#/components/schemas/ProductSpecification'
        productCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic_FVO'
        isBundle:
          type: boolean
          description: Boolean to signify the request is for a bundle purchase.
          default: false
        '@type':
          type: string
          description: Type of fulfillment based on the bundle purchase.
    ProductOrderItem:
      type: object
      properties:
        action:
          type: string
          description: Action placeholder based on the APi request
        product:
          $ref: '#/components/schemas/Product'
        itemPrice:
          type: array
          items:
            $ref: '#/components/schemas/ItemPrice'
        itemTerm:
          type: array
          items:
            $ref: '#/components/schemas/ItemTerm'
    ProductOrderRequest:
      type: object
      required:
      - callbackUrl
      - payment
      - productOrderItem
      properties:
        recurring:
          type: boolean
          description: Placeholder to help some opcos know if subscription with airtime is one-off or to be autorenewed.
          default: false
        sendSMS:
          type: boolean
          description: Used to notify the backend if fulfilment SMS should be sent to the customer.
          default: false
        category:
          type: string
          description: Category of bundle to purchase.
          example: Bundles
        callbackUrl:
          type: string
          description: Completion status handler.
          example: https://eo2uav4rx2cdgbx.m.pipedream.net
        notificationContact:
          type: string
          description: Contact to be notified about the purchase
          example: 256779999565
        externalId:
          type: string
          description: Channel unique id for the transaction.
          example: mad_nextgen_98765434567976765
        state:
          type: string
          enum:
          - acknowledged
          - rejected
          - pending
          - held
          - inProgress
          - cancelled
          - completed
          - failed
          - partial
          - assessingCancellation
          - pendingCancellation
          description: Initial order state
        id:
          type: string
          description: Id placeholder.
        description:
          type: string
          description: Product Order illustration sample
        requestedStartDate:
          type: string
          format: date-time
          example: 2023-01-04T12:25:35.868000+00:00
        requestedCompletionDate:
          type: string
          format: date
          example: 2022-08-21
        note:
          type: array
          items:
            $ref: '#/components/schemas/note'
        channel:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        payment:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        productOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/ProductOrderItem'
    ProductOrderResp:
      type: object
      required:
      - statusCode
      - transactionId
      - statusMessage
      - sequenceNo
      properties:
        statusCode:
          type: string
          description: MADAPI status code
          example: "0000"
        statusMessage:
          type: string
          description: MADAPI status message
          example: Success
        transactionId:
          type: string
          description: Unique transaction identifier.
          example: XXHRE124
        sequenceNo:
          type: string
          description: Request sexuence number
          example: JNL86343
        creationDate:
          type: string
          format: date-time
          example: '2026-07-28T12:34:56Z'
        state:
          type: string
          example: completed
        id:
          type: string
          example: PO123456789
    ProductSpecification:
      type: object
      properties:
        id:
          type: string
          description: Id of the bundle to be purchased.
          example: RACT_UG_Data_200
        name:
          type: string
          description: Name of bundle southbound system.
          example: CIS offer
    Characteristic_FVO:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        '@type':
          type: string
        endDate:
          type: string
          format: date-time
        startDate:
          type: string
          format: date-time
    RelatedParty:
      type: object
      properties:
        id:
          type: string
          example: 256779999565
          description: Id placeholder.
        role:
          type: string
          example: primarymsisdn
          description: Description of the id placeholder.
    TaxIncludedAmount:
      type: object
      properties:
        unit:
          type: string
          description: Unit of price altered.
          example: UGX
        value:
          oneOf:
            - type: number
            - type: string
          description: Amount of price altered.
          example: 200
    Error:
      type: object
      required:
      - statusCode
      - statusMessage
      - supportMessage
      - transactionId
      - sequenceNo
      properties:
        statusCode:
          type: string
          description: This is the MADAPI Canonical Error Code (it is 4 characters
            long and it is not the HTTP Status Code which is 3 characters long). Back-end
            system errors are mapped to specific canonical error codes which are returned.
            More information on these mappings can be found on the MADAPI Confluence
            Page 'Response Codes'
        statusMessage:
          type: string
          description: More details and corrective actions related to the error which
            can be shown to a client
        supportMessage:
          type: string
          description: Internal message meant for consumers of the API to troubleshoot
            the error (could possible include the back-end system error code in the
            message if it would be useful)
        transactionId:
          type: string
          description: This is the same transactionId that is sent in the request
            header.
        sequenceNo:
          type: string
          description: A unique identifier for tracking all requests
          example: '12939993'