Subscriptions v2

AVAILABLE IN

All countries

Download

Download Postman collection Download Swagger

Available endpoints

GET v2/customers/{customerId}/subscriptions

Description

Get a Customer's Subscriptions given the Customer's id

Header parameters

transactionId string
Client generated Id to include for tracing requests
Content-Type application/json

Auth parameters

apikey X-API-Key

Query parameters

subscriptionProviderId string
Subscription Provider to query
200OK
customerId string
services
statusCode string
data
subscriptions
subscriptionId string
Unique system identifier for the Subscription
subscriptionProviderId string
Identifier for the provider within which the Subscription lives
subscriptionName string
Service the customer is subscribed to
subscriptionStatus string
Active,Inactive,Pending
subscriptionDescription string
Description of the service the customer is subscribed to
subscriptionType string
Adhoc,Recurring
subscriptionLength string
Duration of the subscription the customer is subscribed to
registrationChannel string
Channel through which the customer subscribed to the service
startDate string
Start date of the Subscription; full-date notation RFC 3339
endDate string
End date of the Subscription; full-date notation RFC 3339
subscriptionPaymentSource string
Payment balance to use: Airtime, MoMo, EVDS, Loyalty
sendSMSNotification boolean
Should an SMS be sent to the subscriber to inform them of the subscription
beneficiaryId string
Subscription will be added to the beneficiary msisdn, but payment deducted from the main customerId. format will be E.123
email string
Email associated with the Subscription
auto-renew boolean
Recurring subscription to auto-renew at the end of the expiry period
_links
self
href string
_links
self
href string 
{
    "customerId": [],
    "services": []
}
207Multi-Status
customerId string
services
statusCode string
data
subscriptions
subscriptionId string
Unique system identifier for the Subscription
subscriptionProviderId string
Identifier for the provider within which the Subscription lives
subscriptionName string
Service the customer is subscribed to
subscriptionStatus string
Active,Inactive,Pending
subscriptionDescription string
Description of the service the customer is subscribed to
subscriptionType string
Adhoc,Recurring
subscriptionLength string
Duration of the subscription the customer is subscribed to
registrationChannel string
Channel through which the customer subscribed to the service
startDate string
Start date of the Subscription; full-date notation RFC 3339
endDate string
End date of the Subscription; full-date notation RFC 3339
subscriptionPaymentSource string
Payment balance to use: Airtime, MoMo, EVDS, Loyalty
sendSMSNotification boolean
Should an SMS be sent to the subscriber to inform them of the subscription
beneficiaryId string
Subscription will be added to the beneficiary msisdn, but payment deducted from the main customerId. format will be E.123
email string
Email associated with the Subscription
auto-renew boolean
Recurring subscription to auto-renew at the end of the expiry period
_links
self
href string
_links
self
href string 
{
    "customerId": [],
    "services": []
}
400Bad Request
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
401Unauthorized
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
403Forbidden
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
404Not Found
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
405Method Not Allowed
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
500Internal Server Error
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
POST v2/customers/{customerId}/subscriptions

Description

Provision/add a new subscription to the customers account

Header parameters

transactionId string
Client generated Id to include for tracing requests
Content-Type application/json

Auth parameters

apikey X-API-Key

FormData parameters

subscriptionId string required
Unique identifier for the Subscription
subscriptionProviderId string required
Identifier for the provider within which the Subscription lives
subscriptionName string required
Service the customer is subscribed to
subscriptionStatus string
Active, Inactive, Pending
subscriptionDescription string
Description of the service the customer is subscribed to
subscriptionType string
Adhoc, Recurring
subscriptionLength string
Duration of the subscription the customer is subscribed to
registrationChannel string
Channel through which the customer subscribed to the service
startDate string
Start date of the Subscription; full-date notation RFC 3339
endDate string
End date of the Subscription; full-date notation RFC 3339
subscriptionPaymentSource string
Which payment balance to use to pay: Airtime, MoMo, EVDS, Loyalty
sendSMSNotification boolean
Should an SMS be sent to the subscriber to inform them of the subscription
beneficiaryId string
Subscription will be added to the beneficiary, but payment deducted from the main customerId
auto-renew boolean
Recurring subscription to auto-renew at the end of the expiry period
email string
Email address associated with the Subscription
201Created
subscriptionId string
Unique identifier for the Subscription
subscriptionProviderId string
Identifier for the provider within which the Subscription lives
subscriptionName string
Service the customer is subscribed to
subscriptionStatus string
Active,Inactive,Pending
subscriptionDescription string
Description of the service the customer is subscribed to
subscriptionType string
Adhoc,Recurring
subscriptionLength string
Duration of the subscription the customer is subscribed to
registrationChannel string
Channel through which the customer subscribed to the service
startDate string
Start date of the Subscription; full-date notation RFC 3339
endDate string
End date of the Subscription; full-date notation RFC 3339
subscriptionPaymentSource string
Which payment balance to use to pay: Airtime, MoMo, EVDS, Loyalty
sendSMSNotification boolean
Should an SMS be sent to the subscriber to inform them of the subscription
beneficiaryId string
Subscription will be added to the beneficiary, but payment deducted from the main customerId
auto-renew boolean
Recurring subscription to auto-renew at the end of the expiry period
email string
Email address associated with the Subscription 
{
    "subscriptionId": [],
    "subscriptionProviderId": [],
    "subscriptionName": [],
    "subscriptionStatus": [],
    "subscriptionDescription": [],
    "subscriptionType": "Adhoc",
    "subscriptionLength": [],
    "registrationChannel": [],
    "startDate": [],
    "endDate": [],
    "subscriptionPaymentSource": "Airtime",
    "sendSMSNotification": "true",
    "beneficiaryId": [],
    "auto-renew": "false",
    "email": []
}
202Accepted
subscriptionId integer
ID for the Subscription
subscriptionProviderId integer
Identity of the subscription provider hosting the subscription
statusCode integer
Status Code
status string
Active,Inactive,Pending
description string
Details of the result of the unsubscribe action 
{
    "subscriptionId": [],
    "subscriptionProviderId": [],
    "statusCode": [],
    "status": [],
    "description": []
}
400Bad Request
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
401Unauthorized
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
403Forbidden
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
404Not Found
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
405Method Not Allowed
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
500Internal Server Error
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
DELETE v2/customers/{customerId}/subscriptions

Description

Unsubscribe All Subscriptions for a Customer

Header parameters

transactionId string
Client generated Id to include for tracing requests
Content-Type application/json

Auth parameters

apikey X-API-Key

Query parameters

subscriptionProviderId string required
Identity of the subscription provider hosting the subscription

FormData parameters

callbackUrl string
description string
200OK
subscriptionId integer
ID for the Subscription
subscriptionProviderId integer
Identity of the subscription provider hosting the subscription
statusCode integer
Status Code
status string
Unsubscribe successful,Unsubscribe unsuccessful
description string
Details of the result of the unsubscribe action 
{
    "subscriptionId": [],
    "subscriptionProviderId": [],
    "statusCode": [],
    "status": [],
    "description": []
}
400Bad Request
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
401Unauthorized
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
403Forbidden
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
404Not Found
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
405Method Not Allowed
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
500Internal Server Error
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
GET v2/customers/{customerId}/subscriptions/{subscriptionId}

Description

Retrieve specific subscription details for a customer

Header parameters

transactionId string
Client generated Id to include for tracing requests
Content-Type application/json

Auth parameters

apikey X-API-Key

Query parameters

subscriptionProviderId string required
Identity of the subscription provider hosting the subscription
200OK
customerId string
services
statusCode string
data
subscriptions
subscriptionId string
Unique system identifier for the Subscription
subscriptionProviderId string
Identifier for the provider within which the Subscription lives
subscriptionName string
Service the customer is subscribed to
subscriptionStatus string
Active,Inactive,Pending
subscriptionDescription string
Description of the service the customer is subscribed to
subscriptionType string
Adhoc,Recurring
subscriptionLength string
Duration of the subscription the customer is subscribed to
registrationChannel string
Channel through which the customer subscribed to the service
startDate string
Start date of the Subscription; full-date notation RFC 3339
endDate string
End date of the Subscription; full-date notation RFC 3339
subscriptionPaymentSource string
Payment balance to use: Airtime, MoMo, EVDS, Loyalty
sendSMSNotification boolean
Should an SMS be sent to the subscriber to inform them of the subscription
beneficiaryId string
Subscription will be added to the beneficiary msisdn, but payment deducted from the main customerId. format will be E.123
email string
Email associated with the Subscription
auto-renew boolean
Recurring subscription to auto-renew at the end of the expiry period
_links
self
href string
_links
self
href string 
{
    "customerId": [],
    "services": []
}
400Bad Request
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
401Unauthorized
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
403Forbidden
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
404Not Found
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
405Method Not Allowed
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
500Internal Server Error
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
DELETE v2/customers/{customerId}/subscriptions/{subscriptionId}

Description

Delete a specific subscription

Header parameters

transactionId string
Client generated Id to include for tracing requests
Content-Type application/json

Auth parameters

apikey X-API-Key

Query parameters

subscriptionProviderId string required
Identity of the subscription provider hosting the subscription
200OK
subscriptionId integer
ID for the Subscription
subscriptionProviderId integer
Identity of the subscription provider hosting the subscription
statusCode integer
Status Code
status string
Unsubscribe successful,Unsubscribe unsuccessful
description string
Details of the result of the unsubscribe action 
{
    "subscriptionId": [],
    "subscriptionProviderId": [],
    "statusCode": [],
    "status": [],
    "description": []
}
400Bad Request
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
401Unauthorized
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
403Forbidden
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
404Not Found
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
405Method Not Allowed
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
500Internal Server Error
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
GET v2/customers/{customerId}/subscriptions/{subscriptionId}/status/{statusId}

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.

Header parameters

transactionId string
Client generated Id to include for tracing requests
Content-Type application/json

Auth parameters

apikey X-API-Key

Query parameters

subscriptionProviderId string required
Identity of the subscription provider hosting the subscription
200OK
customerId string
services
statusCode string
data
subscriptions
subscriptionId string
Unique system identifier for the Subscription
subscriptionProviderId string
Identifier for the provider within which the Subscription lives
subscriptionName string
Service the customer is subscribed to
subscriptionStatus string
Active,Inactive,Pending
subscriptionDescription string
Description of the service the customer is subscribed to
subscriptionType string
Adhoc,Recurring
subscriptionLength string
Duration of the subscription the customer is subscribed to
registrationChannel string
Channel through which the customer subscribed to the service
startDate string
Start date of the Subscription; full-date notation RFC 3339
endDate string
End date of the Subscription; full-date notation RFC 3339
subscriptionPaymentSource string
Payment balance to use: Airtime, MoMo, EVDS, Loyalty
sendSMSNotification boolean
Should an SMS be sent to the subscriber to inform them of the subscription
beneficiaryId string
Subscription will be added to the beneficiary msisdn, but payment deducted from the main customerId. format will be E.123
email string
Email associated with the Subscription
auto-renew boolean
Recurring subscription to auto-renew at the end of the expiry period
_links
self
href string
_links
self
href string 
{
    "customerId": [],
    "services": []
}
400Bad Request
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
401Unauthorized
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
403Forbidden
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
404Not Found
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
405Method Not Allowed
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
500Internal Server Error
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
GET v2/customers/{customerId}/subscriptions-providers

Description

Show the list of all Subscription providers that a customer may have subscriptions with

Header parameters

transactionId string
Client generated Id to include for tracing requests
Content-Type application/json

Auth parameters

apikey X-API-Key
200OK
customerId string
services
subscriptionProviderName string
Service the customer is subscribed to
subscriptionProviderDescription string
Description of the service the customer is subscribed to
_links
self
href string 
{
    "customerId": [],
    "services": []
}
400Bad Request
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
401Unauthorized
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
403Forbidden
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
404Not Found
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
405Method Not Allowed
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
500Internal Server Error
timestamp string
Error response code
status string
HTTP Status code
error string
Status description
message string
More error details and corrective measures
path string
the path that caused the error 
{
    "timestamp": [],
    "status": [],
    "error": [],
    "message": [],
    "path": []
}
POST v2/callback/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.

Header parameters

Content-Type application/json

Auth parameters

apikey X-API-Key

FormData parameters

subscriptionId integer
ID for the Subscription
subscriptionProviderId integer
Identity of the subscription provider hosting the subscription
statusCode integer required
Status Code
status string
Unsubscribe successful, Unsubscribe unsuccessful
description string required
Details of the result of the unsubscribe action
200OK

Check out some of our other products.

MTN

Usage Management

Retrieve usage history, OOB usage charge and recharge history details for a particular subscriber MSISDN

gh flag ng flag rw flag zm flag
+ 3 more
View
MTN

KYC v1

View the product

ci flag gh flag ng flag sz flag zm flag
+ 4 more
View
MTN

Job Card Management

To facilitate the capability for consumers Job Card Management, to View Pending Job Card and Approve/Reject Job Card Signoff.

ng flag
View