API to fetch Airtime, Currency, Voice, Data and SMS balance details for a subscriber.
swagger: '2.0'
info:
title: Usage Consumption API
description: 'API to fetch Airtime, Currency, Voice, Data and SMS balance details for a subscriber.'
version: '1.0'
host: api.mtn.com
basePath: /usageConsumption/v1/
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: 'https://api.mtn.com/v1/oauth/access_token'
security:
- OAuth2: []
- ApiKeyAuth: []
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.'
type: string
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: "countryCode"
type: string
in: header
required: false
description: Will be used internally by application
- name: "id"
required: true
type: string
in: path
description: "Subscriber ID/ MSISDN of a customer for which usage consumption report to be fetched. example: 250789123456"
x-example: '250788123456'
- name: "usageType"
required: false
type: string
in: query
description: "Type of usage concerned by the bucket, such as voice, sms, data"
enum:
- All
- mainBalance
- currencyBalance
- Voice
- Data
- SMS
- name: "senderID"
required: false
type: string
in: query
description: "Identifies the source system which integrates with MAD API"
- name: "queryMode"
required: false
type: string
in: query
description: "Query mode for which the request is to be returned, pass 0 or this will be assisgned a default value(0)"
- name: "x-origin-channel-id"
required: false
type: string
in: header
description: "The channel consuming the API e.g. chatbot"
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ResponseUsageConsumptionSummary'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/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.'
type: string
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: "countryCode"
type: string
in: header
required: false
description: Will be used internally by application
- name: "id"
required: true
type: string
in: path
description: "Subscriber ID/ MSISDN of a customer for which usage consumption report to be fetched. example: 250789123456"
x-example: '250788123456'
- name: "usageType"
required: true
type: string
in: query
description: "Type of usage concerned by the bucket, such as voice, sms, data"
enum:
- All
- mainBalance
- currencyBalance
- Voice
- Data
- SMS
- name: "senderID"
required: false
type: string
in: query
description: "Identifies the source system which integrates with MAD API"
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ResponseUsageConsumptionDetailedReport'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
definitions:
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: '#/definitions/UsageConsumptionSummary'
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: '#/definitions/UsageConsumptionDetailedReport'
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: '#/definitions/UsageVolumeProduct'
description: Bucket(s) included in the offer or option subscribed.
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: '#/definitions/Bucket'
description: Bucket(s) included in the offer or option subscribed.
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: '#/definitions/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: '#/definitions/EntityRef'
description: Bundle(s) included in the bucket or option subscribed.
offerDetails:
type: array
items:
$ref: '#/definitions/EntityRef'
description: Offer(s) included in the bundle or option subscribed.
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: '#/definitions/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."
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: '#/definitions/UsageVolumeBalance'
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: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/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"
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
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
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"