MTN Customer Subscription Management API — an MTN Group API product published on the MTN Developer Platform (MADAPI) with a downloadable machine-readable definition covering 6 path(s).
swagger: "2.0"
info:
version: "v2.4"
title: "MTN Customer Subscription Management API"
contact:
name: "MTN API Support"
email: "developer-support@mtn.com"
host: "api.mtn.com"
basePath: "/v2"
schemes:
- "https"
consumes:
- "application/json"
produces:
- "application/json"
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: https://api.mtn.com/oauth/client_credential/accesstoken
security:
- ApiKeyAuth: []
- OAuth2: []
paths:
/customers/{customerId}/subscriptions:
get:
tags:
- "Customers"
summary: "List all Subscriptions"
description: "Get a Customer's Subscriptions given the Customer's id"
operationId: "List all Subscriptions"
produces:
- "application/json"
parameters:
- name: "customerId"
in: "path"
description: "ID for the Customer"
required: true
type: "string"
- name: "subscriptionProviderId"
in: "query"
description: Subscription Provider to query
type: string
- name: "transactionId"
in: header
description: Client generated Id to include for tracing requests
type: string
responses:
200:
description: "List of customer's subscriptions"
schema:
$ref: "#/definitions/CustomerSubscription"
207:
description: "Multi-Status response - Partial list of customer's subscriptions"
schema:
$ref: "#/definitions/CustomerSubscription"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
post:
tags:
- "Customers"
summary: "Subscribe the customer to a new service"
description: "Provision/add a new subscription to the customers account"
operationId: "Subscribe the customer to a new service"
parameters:
- name: customerId
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/subscription'
- name: "transactionId"
in: header
description: Client generated Id to include for tracing requests
type: string
- name: rules
in: query
description: "rules"
required: false
type: boolean
default: true
- name: isOptedData
in: query
description: "The bundle containing data is required or not"
required: false
type: boolean
responses:
201:
description: Created
headers:
Location:
type: string
description: Location header will include the link to the newly created subscription
schema:
$ref: "#/definitions/subscription"
202:
description: Accepted
headers:
Location:
type: string
description: Location header will include the link to the status URL for the new subscription
schema:
$ref: "#/definitions/SubscribeAsync"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
delete:
tags:
- Customers
summary: Unsubscribe All Subscriptions for a Customer
description: Unsubscribe All Subscriptions for a Customer
operationId: Delete All subscriptions
produces:
- application/json
parameters:
- name: customerId
in: path
description: id for the Customer
required: true
type: string
- name: subscriptionProviderId
in: query
description: Identity of the subscription provider hosting the subscription
required: true
type: string
- name: callbackUrl
in: body
schema:
$ref: '#/definitions/Callback'
- name: "transactionId"
in: header
description: Client generated Id to include for tracing requests
type: string
responses:
200:
description: Result of the unsubscribe action
schema:
$ref: '#/definitions/Unsubscribe'
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/customers/{customerId}/subscriptions/{subscriptionId}:
get:
tags:
- "Customers"
summary: "Get Subscription details"
description: "Retrieve specific subscription details for a customer"
operationId: "Get Subscription Details"
parameters:
- name: "customerId"
in: "path"
description: "id for the Customer; if id is msisdn, format must be E.123"
required: true
type: "string"
- name: "subscriptionId"
in: "path"
description: "ID for the Subscription"
required: true
type: "string"
- name: "subscriptionProviderId"
in: "query"
description: "Identity of the subscription provider hosting the subscription"
required: true
type: "string"
- name: "transactionId"
in: header
description: Client generated Id to include for tracing requests
type: string
responses:
200:
description: "Subscription details"
schema:
$ref: "#/definitions/CustomerSubscription"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
delete:
tags:
- "Customers"
summary: "Unsubscribe a specific subscription"
description: "Delete a specific subscription"
operationId: "Delete a specific subscription"
produces:
- "application/json"
parameters:
- name: "customerId"
in: "path"
description: "id of the Customer"
required: true
type: "string"
- name: "subscriptionId"
in: "path"
description: "ID for the Subscription"
required: true
type: "string"
- name: "subscriptionProviderId"
in: "query"
description: "Identity of the subscription provider hosting the subscription"
required: true
type: "string"
- name: "transactionId"
in: header
description: Client generated Id to include for tracing requests
type: string
responses:
200:
description: "Result of the unsubscribe action"
schema:
$ref: "#/definitions/Unsubscribe"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/customers/{customerId}/subscriptions/{subscriptionId}/status/{statusId}:
get:
tags:
- "Customers"
summary: "Get provisioning status of a recently added Subscription"
description: "For certain provisioning requests to add a new subscription, the response will be asynchronous, with a status of PENDING.
Use this query to poll the final status of the provisioning, using the transactionID that was used for the original provisioning request."
operationId: "Get Subscription Provisioning Status"
parameters:
- name: "customerId"
in: "path"
description: "id for the Customer; if id is msisdn, format must be E.123"
required: true
type: "string"
- name: "subscriptionId"
in: "path"
description: "ID for the Subscription"
required: true
type: "string"
- name: "subscriptionProviderId"
in: "query"
description: "Identity of the subscription provider hosting the subscription"
required: true
type: "string"
- name: "statusId"
in: "path"
description: "id for the provisioning request that needs to be queried"
required: true
type: "string"
- name: "transactionId"
in: header
description: Client generated Id to include for tracing requests
type: string
responses:
200:
description: "Subscription details"
schema:
$ref: "#/definitions/CustomerSubscription"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/customers/{customerId}/subscriptions-providers:
get:
tags:
- "Customers"
summary: "Retrieve subscription providers"
description: "Show the list of all Subscription providers that a customer may have subscriptions with"
operationId: "Retrieve subscription providers"
parameters:
- name: "customerId"
in: "path"
description: "id for the Customer; if id is msisdn, format must be E.123"
required: true
type: "string"
- name: "transactionId"
in: header
description: Client generated Id to include for tracing requests
type: string
responses:
200:
description: "Subscription details"
schema:
$ref: "#/definitions/CustomerSubscriptionProvider"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
405:
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/callback/delete-all-subscriptions:
post:
tags:
- "Callback"
summary: "Callback service that MTN API will POST to with the result of the DELETE all subscriptions"
description: "The result of the asynchronous DELETE for all a customers subscriptions will be POSTed to the callback URL that the developer must host.
If there were multiple subscriptions, each result will be posted individually as it completes."
operationId: "Callback service that MTN API will POST to with the result of the DELETE all subscriptions"
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/Unsubscribe'
responses:
200:
description: "OK"
'/customers/list/subscriptions':
get:
tags:
- Customers
summary: List of offers per menu code
description: List of offers per menu code
operationId: List of offers per menu code
produces:
- application/json
parameters:
- name: transactionId
in: header
description: Client generated Id to include for tracing requests
type: string
required: false
- name: nodeId
in: query
description: Third parties unique identifier. Can also be called channelId
type: string
default: MADAPI
required: false
- name: partnerName
in: header
description: partnerName
required: false
type: string
- name: menuCode
in: query
description: menuCode
type: string
- name: sequenceNo
in: header
description: sequenceNo
required: false
type: string
- name: subscriptionProviderId
in: query
type: string
description: subscriptionProviderId
required: false
- name: x-country-code
in: header
description: x-country-code
type: string
responses:
'200':
description: List of offers per menu code
schema:
$ref: '#/definitions/OffersPerMenuCode'
definitions:
CustomerSubscription:
type: object
properties:
customerId:
type: string
services:
additionalProperties:
$ref: "#/definitions/SubscriptionServices"
example: {
"vas_hlr": {
"statusCode": "2000",
"data": {
"subscriptionId": "4",
"subscriptionProviderId": "RBT",
"subscriptionName": "CallerTunez",
"subscriptionDescription": null,
"subscriptionStatus": "Inactive",
"subscriptionType": "Adhoc",
"subscriptionLength": null,
"registrationChannel": null,
"startDate": "2019-04-30",
"endDate": "2019-05-06",
"subscriptionPaymentSource": "Airtime",
"sendSMSNotification": true,
"beneficiaryId": null,
"auto-renew": true,
"email": null}
,},"_links": {"self": {"href": "https://api.mtn.com/v2/customers/27832000000/subscriptions"}}}
CustomerSubscriptionProvider:
type: object
properties:
customerId:
type: string
services:
additionalProperties:
$ref: "#/definitions/SubscriptionServicesProviders"
example: {"imi":{"subscriptionProviderName":"MTN Play Services", "subscriptionProviderDescription": "MTN Play services"}}
SubscriptionServices:
properties:
statusCode:
type: string
data:
type: object
properties:
subscriptions:
type: array
items:
$ref: "#/definitions/Subscription"
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
SubscriptionServicesProviders:
properties:
subscriptionProviderName:
type: "string"
default: "null"
description: "Service the customer is subscribed to"
subscriptionProviderDescription:
type: "string"
default: "null"
description: "Description of the service the customer is subscribed to"
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
Callback:
type: object
title: "Callback"
properties:
callbackUrl:
type: string
description:
type: string
Unsubscribe:
type: "object"
title: "unsubscribe"
required:
- "status"
- "statusCode"
- "description"
properties:
subscriptionId:
type: integer
description: "ID for the Subscription"
subscriptionProviderId:
type: integer
description: "Identity of the subscription provider hosting the subscription"
statusCode:
type: integer
description: "Status Code"
status:
$ref: "#/definitions/StatusEnum"
description:
type: "string"
description: "Details of the result of the unsubscribe action"
SubscribeAsync:
type: "object"
title: "SubscribeAsync"
required:
- "status"
- "statusCode"
- "description"
properties:
subscriptionId:
type: integer
description: "ID for the Subscription"
subscriptionProviderId:
type: integer
description: "Identity of the subscription provider hosting the subscription"
statusCode:
type: integer
description: "Status Code"
status:
$ref: "#/definitions/SubscriptionStatusEnum"
default: "Pending"
description:
type: "string"
description: "Details of the result of the unsubscribe action"
Error:
type: "object"
title: "Error"
required:
- "status"
- "message"
properties:
timestamp:
type: "string"
format: "date-time"
description: "Error response code"
status:
type: "string"
description: "HTTP Status code"
error:
type: "string"
description: "Status description"
message:
type: "string"
description: "More error details and corrective measures"
path:
type: "string"
description: "the path that caused the error"
subscription:
type: "object"
title: "subscription"
required:
- "subscriptionId"
- "subscriptionProviderId"
- "subscriptionName"
properties:
subscriptionId:
type: "string"
default: "null"
description: "Unique identifier for the Subscription"
subscriptionProviderId:
type: "string"
default: "null"
description: "Identifier for the provider within which the Subscription lives"
subscriptionName:
type: "string"
default: "null"
description: "Service the customer is subscribed to"
subscriptionStatus:
$ref: "#/definitions/SubscriptionStatusEnum"
subscriptionDescription:
type: "string"
default: "null"
description: "Description of the service the customer is subscribed to"
subscriptionType:
$ref: "#/definitions/SubscriptionTypeEnum"
subscriptionLength:
type: "string"
default: "null"
description: "Duration of the subscription the customer is subscribed to"
registrationChannel:
type: "string"
default: "null"
description: "Channel through which the customer subscribed to the service"
startDate:
type: "string"
format: "date-time"
default: "null"
description: "Start date of the Subscription; full-date notation RFC 3339"
endDate:
type: "string"
format: "date-time"
default: "null"
description: "End date of the Subscription; full-date notation RFC 3339"
subscriptionPaymentSource:
type: "string"
default: "Airtime"
description: "Which payment balance to use to pay: Airtime, MoMo, EVDS, Loyalty"
sendSMSNotification:
type: "boolean"
default: "true"
description: "Should an SMS be sent to the subscriber to inform them of the subscription"
beneficiaryId:
type: "string"
default: "null"
description: "Subscription will be added to the beneficiary, but payment deducted from the main customerId"
auto-renew:
type: "boolean"
default: "false"
description: "Recurring subscription to auto-renew at the end of the expiry period"
email:
type: "string"
default: "null"
description: "Email address associated with the Subscription"
Subscription:
type: "object"
title: "Subscription"
required:
- "subscriptionId"
- "subscriptionProviderId"
- "subscriptionName"
properties:
subscriptionId:
type: "string"
default: "null"
description: "Unique system identifier for the Subscription"
subscriptionProviderId:
type: "string"
default: "null"
description: "Identifier for the provider within which the Subscription lives"
subscriptionName:
type: "string"
default: "null"
description: "Service the customer is subscribed to"
subscriptionStatus:
$ref: "#/definitions/SubscriptionStatusEnum"
subscriptionDescription:
type: "string"
default: "null"
description: "Description of the service the customer is subscribed to"
subscriptionType:
$ref: "#/definitions/SubscriptionTypeEnum"
subscriptionLength:
type: "string"
default: "null"
description: "Duration of the subscription the customer is subscribed to"
registrationChannel:
type: "string"
default: "null"
description: "Channel through which the customer subscribed to the service"
startDate:
type: "string"
format: "date-time"
default: "null"
description: "Start date of the Subscription; full-date notation RFC 3339"
endDate:
type: "string"
format: "date-time"
default: "null"
description: "End date of the Subscription; full-date notation RFC 3339"
subscriptionPaymentSource:
type: "string"
default: "null"
description: "Payment balance to use: Airtime, MoMo, EVDS, Loyalty"
sendSMSNotification:
type: "boolean"
default: "true"
description: "Should an SMS be sent to the subscriber to inform them of the subscription"
beneficiaryId:
type: "string"
default: "null"
description: "Subscription will be added to the beneficiary msisdn, but payment deducted from the main customerId. format will be E.123"
email:
type: "string"
default: "null"
description: "Email associated with the Subscription"
auto-renew:
type: "boolean"
default: "false"
description: "Recurring subscription to auto-renew at the end of the expiry period"
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
SubscriptionStatusEnum:
type: "string"
title: "subscriptionStatusEnum"
default: "null"
example: "Active"
enum:
- "Active"
- "Inactive"
- "Pending"
x-enum-elements:
- name: "Active"
description: "Subscription is active"
- name: "Inactive"
description: "Subscription has been cancelled, paused, or set for deletion at the end of the period. It is listed because the period may still be valid"
- name: "Pending"
description: "Provisioning is still in progress"
StatusEnum:
type: "string"
title: "statusEnum"
example: "Unsubscribe successful"
enum:
- "Unsubscribe successful"
- "Unsubscribe unsuccessful"
SubscriptionTypeEnum:
type: "string"
title: "subscriptionTypeEnum"
default: "Adhoc"
enum:
- "Adhoc"
- "Recurring"
x-enum-elements:
- name: "Adhoc"
description: "Once off subscription, it wont recur or renew"
- name: "Recurring"
description: "Will renew at the end of the period"
SubscriptionPaymentSourceEnum:
type: "string"
title: "subscriptionPaymentSourceEnum"
default: "Airtime"
enum:
- "Airtime"
- "MobileMoney"
- "EVDS"
- "Loyalty"
x-enum-elements:
- name: "Airtime"
description: "Use the airtime balance to pay"
- name: "MobileMoney"
description: "Use MoMo balance to pay"
- name: "EVDS"
description: "Use voucher to pay"
- name: "Loyalty"
description: "Use Loyalty to pay"
OffersPerMenuCode:
type: object
properties:
httpStatus:
type: string
example: "OK"
customerId:
type: string
services:
type: object
properties:
CIS:
$ref: "#/definitions/ServiceDetails"
statusCode:
type: string
example: "0000"
ServiceDetails:
type: object
properties:
httpStatus:
type: string
data:
type: array
items:
$ref: "#/definitions/SubscriptionDetails"
statusCode:
type: string
example: "0000"
SubscriptionDetails:
type: object
properties:
subscriptionId:
type: string
example: "BEN_Combo_1438"
subscriptionProviderId:
type: string
example: "CIS"
subscriptionName:
type: string
example: "2500 (3500F/20J)"
subscriptionDescription:
type: string
example: "Forfaits Mois"
subscriptionStatus:
type: string
example: "Active"
endDate:
type: string
example: "20Days"
amountCharged:
type: number
format: double
example: 2500
subscriptionPaymentSource:
type: string
example: "Combo"
sendSMSNotification:
type: boolean
example: false
autoRenew:
type: boolean
example: false
amountBefore:
type: number
format: double
example: 0.0
amountAfter:
type: number
format: double
example: 0.0
nonGSM:
type: boolean
example: false
cvmoffer:
type: boolean
example: false
isDataConfirmationRequired:
type: boolean
example: true