SPS - Subscriptions
Documentation Powered by Redocly

SPS - Subscriptions (v5)

Download OpenAPI specification:Download

The "Subscription" API provides the ability to manage provisioning actions for a given SIM card, and optionally a device. Each active SIM card is considered as a subscription. The available operations are Activate Subscription, and Update Subscription Status to Suspend, Resume or Cease. Query transaction status provides the current status of an operation.

These APIs respond with an immediate acknowledgement of the request and a notification event upon completion of provisioning activities. Notifications will be sent to the callback url configured in the developer hub. See the details in the callback url step-by-step guide for details on how to configure.

Operations

Provides the capability to activate a SIM, and optionally a device (aka. a subscription)

This API provides the capability to activate subscription with set of products, services for a given subscriber by wholesale customer and instantiate buckets/allowances

Prerequisites:

  1. Check Network Coverage for the given address/location
  2. Check Device compatibility with network
  3. Check SIM availability

Note: wholesaleCustomerId is an optional parameter that allows sub nodes of the customer hierarchy to be actioned upon, e.g. this can be used to specify a particular brand

Note: To activate subscription with BYOD device, EID is required.

header Parameters
X-Correlation-Id
string <uuid> (CorrelationId)
Example: TQA20210903155950999

Correlation Identifier denotes the process flow identifier. This is used for telemetry purposes

wholesaleCustomerId
string (CustomerId) [ 1 .. 12 ] characters ^.*$
Example: 920000108464

Identifier of wholesale customer/partner

Request Body schema: application/json

This is the model of Activate Subscription Request

partnerTransactionId
required
string (PartnerTransactionId) [ 1 .. 36 ] characters ^.*$

Transaction identifier/order identifier used by Wholesale API consumer/partner on trigger of Subscription life cycle requests

subscriberId
required
string [ 1 .. 36 ] characters ^[-a-zA-Z0-9\s].*$

Unique Subscriber Identifier

wholesalePlanId
required
string [ 1 .. 36 ] characters ^[-a-zA-Z0-9\s].*$

Wholesale Plan Identifier

bucketRefId
Array of strings[ items non-empty ]
required
object (Location)

This represents model of Location

billCycleFrequency
string
Default: "MONTHLY"
Value: "MONTHLY"

Bill Cycle Frequency for the subscription

billCycleStartDay
number [ 1 .. 28 ]

Bill Start Day or Offset Day. If billCycleStartDay is not included in payload, then API will default as below

  • If day of system date is in between 1 and 28, then API will consider day of system date
  • else, then API will consider 1 (1st day of month)

gpsi
string [ 11 .. 15 ] characters ^[0-9]{11,15}$

GPSI/MSISDN of active susbcriber

gpsiReservationId
string [ 1 .. 36 ] characters ^.*$

Number selection Transaction id/order identifier, which is submitted to number management system

iccid
string [ 19 .. 20 ] characters ^[0-9]{19,20}$

ICCID

pei
string [ 15 .. 17 ] characters ^[0-9]{15,17}$

PEI or IMEI

eid
string [ 19 .. 32 ] characters ^[0-9]{19,32}$

EID of ESIM

eSIMDeliveryMethod
string
Value: "QR"

eSIM Delivery Method and possible values are QR

Array of objects (Product) [ items ]

Products to be add/remove/update on top of wholesale plan benefits

Responses

Request samples

Content type
application/json
Example
Activate Subscription with GPSI, PEI
Activate Subscription with GPSI, PEI
Activate Subscription without GPSI, PEI
Activate Subscription with GPSI, BYOD PEI
Activate Subscription without GPSI, BYOD PEI
{
  • "partnerTransactionId": "Txn101010101",
  • "subscriberId": "Sub001",
  • "wholesalePlanId": "Plan001",
  • "bucketRefId": [
    ],
  • "location": {
    },
  • "billCycleFrequency": "MONTHLY",
  • "billCycleStartDay": 1,
  • "gpsi": "19459986891",
  • "gpsiReservationId": "GRID368599719",
  • "iccid": "11986621644523024501",
  • "pei": "2288151828896431",
  • "eSIMDeliveryMethod": "QR",
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "Success"
}

Provides the capability to submit suspend/resume/cease/reactivate subscription request for a given wholesale customer Id

This method provides the capability submit suspend/resume/cease/reactivate request for the given subscription of the given wholesale customer

Conditions:

  • Suspend can be performed on active subscription
  • Resume can be performed on suspended subscription
  • Cease can be performed on active subscription
  • Reactivate can be performed on ceased subscription

Note:
wholesaleCustomerId is an optional parameter that allows sub nodes of the customer hierarchy to be actioned upon, e.g. this can be used to specify a particular brand
header Parameters
X-Correlation-Id
string <uuid> (CorrelationId)
Example: TQA20210903155950999

Correlation Identifier denotes the process flow identifier. This is used for telemetry purposes

wholesaleCustomerId
string (CustomerId) [ 1 .. 12 ] characters ^.*$
Example: 920000108464

Identifier of wholesale customer/partner

Request Body schema: application/json

This is the model of update subscription status request

One of
partnerTransactionId
required
string [ 1 .. 36 ] characters ^.*$

Transaction identifier/order identifier of Wholesale API consumer/partner

iccid
required
string [ 19 .. 20 ] characters ^[0-9]{19,20}$

ICCID of active SIM for a valid subscription

action
required
string
Enum: "Suspend" "Resume" "Cease" "Reactivate"

Action to be performed on a valid subscription

Responses

Request samples

Content type
application/json
Example
UpdateSubscriptionStatusRequestWithGPSI
UpdateSubscriptionStatusRequestWithGPSI
UpdateSubscriptionStatusRequestWithICCID
{
  • "partnerTransactionId": "Txn101010101",
  • "gpsi": 19459986891,
  • "action": "Suspend"
}

Response samples

Content type
application/json
{
  • "status": "Success"
}

Provides the capability to query transaction status for the given partnerTransactionId on Subscription Life Cycle Management

Get Transaction Status

This method provides the capability to query transaction status for the given partnerTransactionId, which is used for trigger the below asynchronous transaction requests. The following transaction types support the query capability:
  1. Activate Subscription
  2. Update Subscription Status (Suspend/Resume/Cease)
  3. PortIn Activate Subscription
  4. Change Device/SIM
  5. Change GPSI
  6. Change GPSI Port-In
  7. Block/Unblock SIM
  8. BlockList Add/Remove Device
  9. Subscription MACD

Note:
wholesaleCustomerId is an optional parameter that allows sub nodes of the customer hierarchy to be actioned upon, e.g. this can be used to specify a particular brand

Example API invocation:
  • Get Transaction Status:/transaction/status/pte0000112
    where pte0000112 is the partner transaction id passed on the original transaction request.
path Parameters
partnerTransactionId
required
string (PartnerTransactionId) [ 1 .. 36 ] characters ^.*$
Example: WhlSlOrd12345

Transaction identifier/order identifier used by Wholesale API consumer/partner on trigger of Subscription life cycle requests

header Parameters
X-Correlation-Id
string <uuid> (CorrelationId)
Example: TQA20210903155950999

Correlation Identifier denotes the process flow identifier. This is used for telemetry purposes

wholesaleCustomerId
string (CustomerId) [ 1 .. 12 ] characters ^.*$
Example: 920000108464

Identifier of wholesale customer/partner

Responses

Response samples

Content type
application/json
{
  • "status": "Success"
}