MTN Group Usage Managements S Sd API

openapi: 3.2.0
info:
  title: Mtn Group Usage Managements S Sd API
  version: 3.0.0 - Last updated date:2026-06-26 09:07:34
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  description: 'Operations tagged UsageManagementsSSd across 2 of this provider''s published API definitions: mtn-group-tmf-usage-management-tmf635.yml, mtn-group-usage-management.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: UsageManagementsSSd
paths:
  /recharge/{id}:
    get:
      tags:
      - UsageManagementsSSd
      summary: Retrieves recharge history and top-up transactions for a subscriber MSISDN via GET /recharge/{id} on the SSD deployment profile, including financial trace fields and paging metadata resolved through the same streamlined routing model used for other SSD usage endpoints.
      description: This operation retrieves comprehensive recharge history details for a subscriber, supporting financial tracking, transaction analysis, and customer service with complete recharge transaction records.
      operationId: UsageManagementsSSd_get_getRechargeHistory_rechargeid
      parameters:
      - name: appName
        in: query
        required: false
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        schema:
          type: string
      - name: endTime
        in: query
        required: false
        schema:
          type: string
      - name: historyType
        in: query
        required: false
        schema:
          type: string
      - name: hostName
        in: query
        required: false
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: string
      - name: maxRecords
        in: query
        required: false
        schema:
          type: string
      - name: pageNum
        in: query
        required: false
        schema:
          type: string
      - name: pageSize
        in: query
        required: false
        schema:
          type: string
      - name: referenceID
        in: query
        required: false
        schema:
          type: string
      - name: startTime
        in: query
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: true
        schema:
          type: string
      - name: userID
        in: query
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI usage management flows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_res_RechargeResponse'
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '502':
          description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '503':
          description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      deprecated: false
    servers:
    - url: https://api.mtn.com/v1
      description: Production Server
  /usage/{id}:
    get:
      tags:
      - UsageManagementsSSd
      summary: Retrieves consolidated usage history for a subscriber MSISDN via GET /usage/{id} on the SSD deployment profile, including SMS, voice, and data records with pagination and downstream routing to the configured single-system usage path for the requesting country.
      description: This operation retrieves all the call details record for a subscriber like SMS, Voice and Data usage history with comprehensive transaction tracking and detailed usage analytics.
      operationId: UsageManagementsSSd_get_getUsageByID_usageid
      parameters:
      - name: appName
        in: query
        required: false
        schema:
          type: string
      - name: attributes
        in: query
        required: false
        schema:
          type: string
      - name: countryCode
        in: header
        required: true
        schema:
          type: string
      - name: endTime
        in: query
        required: false
        schema:
          type: string
      - name: hostName
        in: query
        required: false
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: maxRecords
        in: query
        required: false
        schema:
          type: string
      - name: noOfDays
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pageNumber
        in: query
        required: false
        schema:
          type: string
      - name: pageSize
        in: query
        required: false
        schema:
          type: string
      - name: referenceID
        in: query
        required: false
        schema:
          type: string
      - name: startTime
        in: query
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: true
        schema:
          type: string
      - name: usageType
        in: query
        required: true
        schema:
          type: string
      - name: userID
        in: query
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI usage management flows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_res_UsageResponse'
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '502':
          description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '503':
          description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      deprecated: false
    servers:
    - url: https://api.mtn.com/v1
      description: Production Server
  /usageCharge/{id}:
    get:
      tags:
      - UsageManagementsSSd
      summary: Retrieves out-of-bundle usage charge lines for a subscriber MSISDN via GET /usageCharge/{id} on the SSD deployment profile, returning rated beyond-bundle consumption with paging and downstream retrieval aligned to the simplified system selection rules for this stack.
      description: This operation retrieves comprehensive out of bundle usage charges applied to a subscriber, supporting detailed billing analysis, cost tracking, and financial reporting with complete charge breakdown.
      operationId: UsageManagementsSSd_get_getUsageChargeByID_usageChargeid
      parameters:
      - name: appName
        in: query
        required: false
        schema:
          type: string
      - name: countryCode
        in: header
        required: true
        schema:
          type: string
      - name: endTime
        in: query
        required: false
        schema:
          type: string
      - name: hostName
        in: query
        required: false
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: maxRecords
        in: query
        required: false
        schema:
          type: string
      - name: pageNumber
        in: query
        required: false
        schema:
          type: string
      - name: pageSize
        in: query
        required: false
        schema:
          type: string
      - name: referenceID
        in: query
        required: false
        schema:
          type: string
      - name: startTime
        in: query
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: true
        schema:
          type: string
      - name: usageType
        in: query
        required: true
        schema:
          type: string
      - name: userID
        in: query
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI usage management flows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_res_UsageChargeResponse'
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '502':
          description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '503':
          description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      deprecated: false
    servers:
    - url: https://api.mtn.com/v1
      description: Production Server
components:
  schemas:
    rw_co_mtn_usage_aggregator_model_data_UsageDataResponse:
      title: UsageDataResponse
      type: object
      properties:
        id:
          type: string
        description:
          type: string
        usageDate:
          type: string
        balanceType:
          type: string
        usageType:
          type: string
        status:
          type: string
        usageCharacteristic:
          type: array
          items:
            title: UsageCharacteristic
            type: object
            properties:
              name:
                type: string
              valueType:
                type: string
              value:
                type: string
              units:
                type: string
        usageSpecification:
          title: UsageSpecification
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            duration:
              type: string
            amount:
              type: string
            startTime:
              type: string
            endTime:
              type: string
        ratedProductUsage:
          type: array
          items:
            title: RatedProductUsage
            type: object
            properties:
              bucketValueConvertedInAmount:
                title: CommonUnit
                type: object
                properties:
                  unit:
                    type: string
                  value:
                    type: string
                  amount:
                    type: string
              otherDetails:
                title: OtherDetails
                type: object
                properties:
                  byteSent:
                    type: string
                  byteReceived:
                    type: string
                  balanceBefore:
                    type: string
                  balanceAfter:
                    type: string
                  daysOfvalidity:
                    type: string
                  unitBalanceBefore:
                    type: string
                  rate:
                    type: string
                  usedUnits:
                    type: string
                  balanceDetails:
                    type: array
                    items:
                      title: BalanceDetails
                      type: object
                      properties:
                        accountId:
                          type: string
                        amountBefore:
                          type: string
                        amountAfter:
                          type: string
                        amountCharged:
                          type: string
                  amountBefore:
                    type: string
                  amountAfter:
                    type: string
                  usedValue:
                    type: string
                  balanceType:
                    type: string
        binaryAttachment:
          type: array
          items:
            title: BinaryAttachment
            type: object
            properties:
              id:
                type: string
                format: byte
              href:
                type: string
              attachmentType:
                type: string
              content:
                type: string
                format: byte
              description:
                type: string
              mimeType:
                type: string
              name:
                type: string
        gsm:
          title: UsageGsm
          type: object
          properties:
            spend:
              title: UsageSpend
              type: object
              properties:
                spendM1:
                  type: string
                spendM2:
                  type: string
                spendM3:
                  type: string
                spendM4:
                  type: string
                spendM5:
                  type: string
                spendM6:
                  type: string
                spendM7:
                  type: string
                spendM8:
                  type: string
                spendM9:
                  type: string
                spendM10:
                  type: string
                spendM11:
                  type: string
                spendM12:
                  type: string
                spendMtd:
                  type: string
                spendYtd:
                  type: string
                spendPersMtd:
                  type: string
                spendPersYtd:
                  type: string
            avgMonthlySpend:
              type: string
        band:
          title: UsageBand
          type: object
          properties:
            calendarCategoryYtd:
              type: string
            calendarCategoryAnnual:
              type: string
            personalCategoryAnnual:
              type: string
            personalCycleStartDate:
              type: string
            personalCycleEndDate:
              type: string
            personalCategoryYtd:
              type: string
            personalCycleFirstDate:
              type: string
        voiceCharge:
          title: UsageUnit
          type: object
          properties:
            unit:
              type: string
            amount:
              type: string
        smsCharge:
          $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_res_UsageUnit'
        dataCharge:
          $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_res_UsageUnit'
        dateTime:
          type: string
        networkCd:
          type: string
        name:
          type: string
        processedTime:
          type: string
        transactionDate:
          type: string
        daysOfValidity:
          type: string
        code:
          type: string
        expiryDate:
          type: string
        frequency:
          type: string
        offerId:
          type: string
        calledMSISDN:
          type: string
        flag:
          type: string
        accessPointName:
          type: string
        networkType:
          type: string
        chargingContextId:
          type: string
        payType:
          type: string
        cellId:
          type: string
        usageNumber:
          type: string
        traffic:
          type: string
        operator:
          type: string
        systemCd:
          type: string
        callDuration:
          type: string
        accumulatorCount:
          type: string
        eventCallDetail:
          type: string
        paymentMethod:
          type: string
        incomingDataVolume:
          type: string
        bundleName:
          type: string
        productName:
          type: string
        amount:
          type: string
        submittedTime:
          type: string
        simActivationDate:
          type: string
        lastActivityDate:
          type: string
        accountDetails:
          type: array
          items:
            title: AccountDetails
            type: object
            properties:
              id:
                type: string
              balanceBefore:
                type: number
                format: double
              balanceAfter:
                type: string
              change:
                type: number
                format: double
        additionalInformation:
          type: array
          items:
            title: AdditionalInformation
            type: object
            properties:
              name:
                type: string
              value:
                type: string
        is_payable_gc:
          type: string
        gross_act:
          type: string
        is_pending_eyeballing:
          type: string
        is_gross_connection:
          type: string
        is_ads_gc:
          type: string
        is_rejected_sim:
          type: string
        date_key:
          type: string
        dealer_email:
          type: string
        is_med_low_sim:
          type: string
        momo_wallet:
          type: string
        is_quarantine_sim:
          type: string
        msisdn_key:
          type: string
        is_smartphone_ads:
          type: string
        dealer:
          type: string
        sim_swap_request:
          type: string
        failed_swap:
          type: string
        agent_email:
          type: string
        pending_swap:
          type: string
        successful_swap:
          type: string
        rejected_swap:
          type: string
    rw_co_mtn_usage_aggregator_model_res_RechargeResponse:
      title: RechargeResponse
      type: object
      properties:
        resultCode:
          type: string
        resultDescription:
          type: string
        transactionId:
          type: string
        sequenceNumber:
          type: string
        referenceId:
          type: string
        requestDate:
          type: string
        maxRecs:
          type: string
        numRecs:
          type: string
        pageNum:
          type: string
        dateRange:
          type: string
        duration:
          type: string
        data:
          type: array
          items:
            title: RechargeData
            type: object
            properties:
              subscriberId:
                type: string
              rechargeDate:
                type: string
              adjustmentType:
                type: string
              amountBefore:
                type: string
              amountAfter:
                type: string
              transaction:
                type: string
              rechargeDescription:
                type: string
              rechargeHistory:
                type: array
                items:
                  title: RechargeHistory
                  type: object
                  properties:
                    description:
                      type: string
                    payType:
                      type: string
                    rechargeAmount:
                      type: string
                    unit:
                      type: string
                    partnerCode:
                      type: string
              recharge:
                type: array
                items:
                  $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_data_RechargeHistory'
        rechargeHistory:
          type: array
          items:
            $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_data_RechargeData'
    rw_co_mtn_usage_aggregator_model_data_UsageChargeData:
      title: UsageChargeData
      type: object
      properties:
        usageDate:
          type: string
        voiceCharge:
          $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_common_CommonUnit'
        smsCharge:
          $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_common_CommonUnit'
        dataCharge:
          $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_common_CommonUnit'
    rw_co_mtn_usage_aggregator_model_data_RechargeData:
      title: RechargeData
      type: object
      properties:
        subscriberId:
          type: string
        rechargeDate:
          type: string
        adjustmentType:
          type: string
        amountBefore:
          type: string
        amountAfter:
          type: string
        transaction:
          type: string
        rechargeDescription:
          type: string
        rechargeHistory:
          type: array
          items:
            title: RechargeHistory
            type: object
            properties:
              description:
                type: string
              payType:
                type: string
              rechargeAmount:
                type: string
              unit:
                type: string
              partnerCode:
                type: string
        recharge:
          type: array
          items:
            $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_data_RechargeHistory'
    rw_co_mtn_usage_aggregator_model_res_UsageChargeResponse:
      title: UsageChargeResponse
      type: object
      properties:
        resultCode:
          type: string
        resultDescription:
          type: string
        transactionId:
          type: string
        sequenceNumber:
          type: string
        referenceId:
          type: string
        requestDate:
          type: string
        maxRecs:
          type: string
        numRecs:
          type: string
        pageNum:
          type: string
        data:
          type: array
          items:
            title: UsageChargeData
            type: object
            properties:
              usageDate:
                type: string
              voiceCharge:
                $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_common_CommonUnit'
              smsCharge:
                $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_common_CommonUnit'
              dataCharge:
                $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_common_CommonUnit'
        usageCharge:
          type: array
          items:
            $ref: '#/components/schemas/rw_co_mtn_usage_aggregator_model_data_UsageChargeData'
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
          example: '400'
        statusMessage:
          type: string
          description: Human-readable error message
          example: Bad request. Invalid parameters provided.
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
          example: VALIDATION_ERROR
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
          example: '1234567890'
        sequenceNo:
          type: string
          description: Sequence number for request tracking
          example: '20250115120000001'
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
          example: 2025-01-15 12:00:00+00:00
        path:
          type: string
          description: API endpoint path where the error occurred
          example: /api/v1/resource
        method:
          type: string
          description: HTTP method of the request that caused the error
          example: POST
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
      example:
        statusCode: '400'
        statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors.
        supportMessage: API_ERROR
        transactionId: '1234567890'
        sequenceNo: '20250115120000001'
        timestamp: 2025-01-15 12:00:00+00:00
    rw_co_mtn_usage_aggregator_model_res_UsageUnit:
      title: UsageUnit
      type: object
      properties:
        unit:
          type: string
        amount:
          type: string
    rw_co_mtn_usage_aggregator_model_common_CommonUnit:
      title: CommonUnit
      type: object
      properties:
        unit:
          type: string
        value:
          type: string
        amount:
          type: string
    rw_co_mtn_usage_aggregator_model_res_UsageResponse:
      title: UsageResponse
      type: object
      properties:
        resultCode:
          type: string
        resultDescription:
          type: string
        transactionId:
          type: string
        msisdn:
          type: string
        referenceId:
          type: string
        requestDate:
          type: string
        maxRecords:
          type: string
        pageNumber:
          type: string
        numRecords:
          type: string
        dateRanges:
          type: array
          items:
            type: string
        sequenceNumber:
          type: string
        submittedTime:
          type: string
        requestRange:
          type: string
        maximumRecord:
          type: string
        numOfRecord:
          type: string
        pageNum:
          type: string
        noOfRecords:
          type: string
        requestTime:
          type: string
        duration:
          type: integer
          format: int32
        dateRange:
          type: string
        data:
          type: array
          items:
            title: UsageDataResponse
            type: object
            properties:
              id:
                type: string
              description:
                type: string
              usageDate:
                type: string
              balanceType:
                type: string
              usageType:
                type: string
              status:
                type: string
              usageCharacteristic:
                type: array
                items:
                  title: UsageCharacteristic
                  type: object
                  properties:
                    name:
                      type: string
                    valueType:
                      type: string
                    value:
                      type: string
                    units:
                      type: string
              usageSpecification:
                title: UsageSpecification
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  duration:
                    type: string
                  amount:
                    type: string
                  startTime:
                    type: string
                  endTime:
                    type: string
              ratedProductUsage:
                type: array
                items:
                  title: RatedProductUsage
                  type: object
                  properties:
     

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-usagemanagementsssd-api-openapi.yml