MTN Group Usage Consumption Report API

openapi: 3.2.0
info:
  title: Mtn Group Usage Consumption Report API
  version: '1.0'
  description: 'Operations tagged usageConsumptionReport across 2 of this provider''s published API definitions: mtn-group-tmf-usage-consumption-tmf677.yml, mtn-group-usage-consumption.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/usageConsumption/v1/
tags:
- name: usageConsumptionReport
paths:
  /usageConsumptionSummary/{id}:
    get:
      operationId: retrieveUsageConsumptionSummary
      summary: Retrieves a usage consumption summary of a subscriber
      description: This operation is used to retrieve usage consumption summary/report of a subscriber.
      tags:
      - usageConsumptionReport
      parameters:
      - name: transactionId
        in: header
        required: true
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        description: Will be used internally by application
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: 'Subscriber ID/ MSISDN of a customer for which usage consumption report to be fetched. example: 250789123456'
        x-example: '250788123456'
        schema:
          type: string
      - name: usageType
        required: false
        in: query
        description: Type of usage concerned by the bucket, such as voice, sms, data
        schema:
          type: string
          enum:
          - All
          - mainBalance
          - currencyBalance
          - Voice
          - Data
          - SMS
      - name: senderID
        required: false
        in: query
        description: Identifies the source system which integrates with MAD API
        schema:
          type: string
      - name: queryMode
        required: false
        in: query
        description: Query mode for which the request is to be returned, pass 0 or this will be assisgned a default value(0)
        schema:
          type: string
      - name: x-origin-channel-id
        required: false
        in: header
        description: The channel consuming the API e.g. chatbot
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ResponseUsageConsumptionSummary'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - OAuth2: []
      - ApiKeyAuth: []
    servers:
    - url: https://api.mtn.com/usageConsumption/v1/
  /usageConsumptionDetailedReport/{id}:
    get:
      operationId: retrieveUsageConsumptionDetailedReport
      summary: Retrieves a usage consumption Detailed Report of a subscriber
      description: This operation is used to retrieve usage consumption Detailed report of a subscriber.
      tags:
      - usageConsumptionReport
      parameters:
      - name: transactionId
        in: header
        required: true
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        description: Will be used internally by application
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: 'Subscriber ID/ MSISDN of a customer for which usage consumption report to be fetched. example: 250789123456'
        x-example: '250788123456'
        schema:
          type: string
      - name: usageType
        required: true
        in: query
        description: Type of usage concerned by the bucket, such as voice, sms, data
        schema:
          type: string
          enum:
          - All
          - mainBalance
          - currencyBalance
          - Voice
          - Data
          - SMS
      - name: senderID
        required: false
        in: query
        description: Identifies the source system which integrates with MAD API
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ResponseUsageConsumptionDetailedReport'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - OAuth2: []
      - ApiKeyAuth: []
    servers:
    - url: https://api.mtn.com/usageConsumption/v1/
components:
  schemas:
    Error:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        status:
          type: string
          description: Status/Error code returned from the provider system
        error:
          type: string
          description: Status/Error description
        message:
          type: string
          description: More error details and corrective measures
        path:
          type: string
          description: the path that caused the error
    UsageVolumeBalance:
      type: object
      description: The balance (called UsageVolumeBalance in the SID model) defines the remaining allowed product usage quantity in terms of volume, time, currency or events. It corresponds to the initial allowed usage quantity minus the usage consumed on the bucket.
      properties:
        initialValue:
          $ref: '#/components/schemas/Quantity'
          description: Numeric initial value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example
        usedValue:
          $ref: '#/components/schemas/Quantity'
          description: Numeric used value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example
        remainingValue:
          $ref: '#/components/schemas/Quantity'
          description: Numeric remaining value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Balance period between a start date time and an end date time. For prepaid bucket, the period of the balance is between the  effective date of the usage consumption report generation and the end date of the bucket. For postpaid bucket, the period of the balance is between the effective date of the usage consumption report generation and the next bill date.
        currencyId:
          type: string
          description: Currency ID
          example: '1185'
        currencyName:
          type: string
          description: Name of the currency
          example: SSD
    UsageConsumptionSummary:
      type: object
      description: An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example).
      properties:
        id:
          type: string
          description: Unique identifier
        type:
          type: string
          description: Type of unique identifier.
        description:
          type: string
          description: Description of the entity
        name:
          type: string
          description: Name of the entity.
        subscriberType:
          type: string
          description: Type of subscriber such as Prepaid, Postpaid, Hybrid etc.
          enum:
          - Prepaid
          - Postpaid
          - Hybrid
        usageType:
          type: string
          description: Type of usage concerned by the bucket, such as voice, sms, data
        bucket:
          type: array
          items:
            $ref: '#/components/schemas/UsageVolumeProduct'
          description: Bucket(s) included in the offer or option subscribed.
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end
    Quantity:
      type: object
      description: An amount in a given unit
      properties:
        amount:
          default: 1
          type: number
          format: float
          description: Numeric value in a given unit
        units:
          type: string
          description: Unit
    UsageVolumeProduct:
      type: object
      description: A bucket (called UsageVolumeProduct in the SID model) represents a quantity of usage, as 2 hours national calls or 50 sms for example. It could be either a quantity or an amount in a currency (i.e. It could represent a fixed number of SMS, MMS, minutes of calls, quantity of data, number of events as well as a specific amount in a given currency). It requires one or more network products from which usages will debit the bucket.
      properties:
        id:
          type: string
          description: Unique identifier of the bucket
        name:
          type: string
          description: Bucket name
        description:
          type: string
          description: Description of the relative entity.
        type:
          type: string
          description: This is the type of relative entity.
        bucketBalance:
          type: array
          items:
            $ref: '#/components/schemas/UsageVolumeBalance'
    UsageConsumptionDetailedReport:
      type: object
      description: An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example).
      properties:
        id:
          type: string
          description: Unique identifier
        type:
          type: string
          description: Type of unique identifier.
        description:
          type: string
          description: Description of the entity
        name:
          type: string
          description: Name of the entity.
        subscriberType:
          type: string
          description: Type of subscriber such as Prepaid, Postpaid, Hybrid etc.
          enum:
          - Prepaid
          - Postpaid
          - Hybrid
        usageType:
          type: string
          description: Type of usage concerned by the bucket, such as voice, sms, data
        bucket:
          type: array
          items:
            $ref: '#/components/schemas/Bucket'
          description: Bucket(s) included in the offer or option subscribed.
    ResponseUsageConsumptionDetailedReport:
      type: object
      required:
      - resultCode
      - resultDescription
      - transactionId
      - data
      properties:
        resultCode:
          example: '0000'
          type: string
          description: Result code. Example- '0000'
        resultDescription:
          example: Success
          type: string
          description: Result message. Example- 'Successfully processed'
        transactionId:
          example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
          type: string
          description: Transaction id returned by the provider system.
        data:
          type: array
          items:
            $ref: '#/components/schemas/UsageConsumptionDetailedReport'
    Bucket:
      type: object
      description: An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example).
      properties:
        id:
          type: string
          description: Unique identifier
        type:
          type: string
          description: Type of unique identifier.
        description:
          type: string
          description: Description of the entity
        name:
          type: string
          description: Name of the entity.
        remainingAmount:
          $ref: '#/components/schemas/Quantity'
          description: Remaining balance of the entity
        activationDate:
          type: string
          format: date
          description: Activation date of the entity
        expiryDate:
          type: string
          format: date
          description: Expiry date of the entity
        bundleDetails:
          type: array
          items:
            $ref: '#/components/schemas/EntityRef'
          description: Bundle(s) included in the bucket or option subscribed.
        offerDetails:
          type: array
          items:
            $ref: '#/components/schemas/EntityRef'
          description: Offer(s) included in the bundle or option subscribed.
    ResponseUsageConsumptionSummary:
      type: object
      required:
      - resultCode
      - resultDescription
      - transactionId
      - data
      properties:
        resultCode:
          example: '0000'
          type: string
          description: Result code. Example- '0000'
        resultDescription:
          example: Success
          type: string
          description: Result message. Example- 'Successfully processed'
        transactionId:
          example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
          type: string
          description: Transaction id returned by the provider system.
        data:
          type: array
          items:
            $ref: '#/components/schemas/UsageConsumptionSummary'
    EntityRef:
      type: object
      description: An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example).
      properties:
        id:
          type: string
          description: Unique identifier
        type:
          type: string
          description: Type of unique identifier.
        description:
          type: string
          description: Description of the entity
        name:
          type: string
          description: Name of the entity.
        remainingAmount:
          $ref: '#/components/schemas/Quantity'
          description: Remaining balance of a bucket
        activationDate:
          type: string
          format: date
          description: Activation date of the bucket
        expiryDate:
          type: string
          format: date
          description: Expiry date of the bucket
        validity:
          type: string
          description: Validity of the entity
        recurring:
          type: boolean
          default: false
          description: Nature of entity, i.e., one-time or recurring.
        recurringDate:
          type: string
          format: date
          description: Recuuring date of the entity.
    UsageVolumeBalance_2:
      type: object
      description: The balance (called UsageVolumeBalance in the SID model) defines the remaining allowed product usage quantity in terms of volume, time, currency or events. It corresponds to the initial allowed usage quantity minus the usage consumed on the bucket.
      properties:
        initialValue:
          $ref: '#/components/schemas/Quantity'
          description: Numeric initial value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example
        usedValue:
          $ref: '#/components/schemas/Quantity'
          description: Numeric used value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example
        remainingValue:
          $ref: '#/components/schemas/Quantity'
          description: Numeric remaining value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Balance period between a start date time and an end date time. For prepaid bucket, the period of the balance is between the  effective date of the usage consumption report generation and the end date of the bucket. For postpaid bucket, the period of the balance is between the effective date of the usage consumption report generation and the next bill date.
    UsageConsumptionSummary_2:
      type: object
      description: 'An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). '
      properties:
        id:
          type: string
          description: Unique identifier
        type:
          type: string
          description: Type of unique identifier.
        description:
          type: string
          description: Description of the entity
        name:
          type: string
          description: Name of the entity.
        subscriberType:
          type: string
          description: Type of subscriber such as Prepaid, Postpaid, Hybrid etc.
          enum:
          - Prepaid
          - Postpaid
          - Hybrid
        usageType:
          type: string
          description: Type of usage concerned by the bucket, such as voice, sms, data
        bucket:
          type: array
          items:
            $ref: '#/components/schemas/UsageVolumeProduct'
          description: Bucket(s) included in the offer or option subscribed.
    UsageConsumptionDetailedReport_2:
      type: object
      description: 'An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). '
      properties:
        id:
          type: string
          description: Unique identifier
        type:
          type: string
          description: Type of unique identifier.
        description:
          type: string
          description: Description of the entity
        name:
          type: string
          description: Name of the entity.
        subscriberType:
          type: string
          description: Type of subscriber such as Prepaid, Postpaid, Hybrid etc.
          enum:
          - Prepaid
          - Postpaid
          - Hybrid
        usageType:
          type: string
          description: Type of usage concerned by the bucket, such as voice, sms, data
        bucket:
          type: array
          items:
            $ref: '#/components/schemas/Bucket_2'
          description: Bucket(s) included in the offer or option subscribed.
    Bucket_2:
      type: object
      description: 'An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). '
      properties:
        id:
          type: string
          description: Unique identifier
        type:
          type: string
          description: Type of unique identifier.
        description:
          type: string
          description: Description of the entity
        name:
          type: string
          description: Name of the entity.
        remainingAmount:
          $ref: '#/components/schemas/Quantity'
          description: Remaining balance of the entity
        activationDate:
          type: string
          format: date
          description: Activation date of the entity
        expiryDate:
          type: string
          format: date
          description: Expiry date of the entity
        bundleDetails:
          type: array
          items:
            $ref: '#/components/schemas/EntityRef_2'
          description: Bundle(s) included in the bucket or option subscribed.
        offerDetails:
          type: array
          items:
            $ref: '#/components/schemas/EntityRef_2'
          description: Offer(s) included in the bundle or option subscribed.
    EntityRef_2:
      type: object
      description: 'An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). '
      properties:
        id:
          type: string
          description: Unique identifier
        type:
          type: string
          description: Type of unique identifier.
        description:
          type: string
          description: Description of the entity
        name:
          type: string
          description: Name of the entity.
        remainingAmount:
          $ref: '#/components/schemas/Quantity'
          description: Remaining balance of a bucket
        activationDate:
          type: string
          format: date
          description: Activation date of the bucket
        expiryDate:
          type: string
          format: date
          description: Expiry date of the bucket
        validity:
          type: string
          description: Validity of the entity
        recurring:
          type: boolean
          default: false
          description: Nature of entity, i.e., one-time or recurring.
        recurringDate:
          type: string
          format: date
          description: Recuuring date of the entity.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/v1/oauth/access_token
x-refined-from:
- mtn-group-tmf-usage-consumption-tmf677.yml
- mtn-group-usage-consumption.yml