A subscription acts as a contract between the sales vendor and the customer. Usually, the platform is configured so that a subscription for an offer is created after the corresponding sales order is paid for.
In this document:
The platform exposes operations with its subscriptions on the /subscriptions endpoints.
An API client can get the full list of orders or narrow down the returned list by adding certain search criteria to a request.
To get the full list of a subscriptions, send the following request:
GET /subscriptions HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16
The response looks similar to the following:
HTTP/1.1 200 OK
{
"data": [
{
"id": "1000177",
"customerId": "1000275",
"status": "active",
"renewalStatus": true,
"creationDate": "2019-10-25",
"renewalDate": "2020-10-23",
"lastModifiedDate": "2019-10-25"
}
],
"pagination": {
"offset": 0,
"limit": 10,
"total": 1
}
}
The returned list of subscriptions can be narrowed down by the following query parameters:
customerId
: the ID of the subscriber
status
: the subscription status that can be one of [“pending”, “active”, “hold”, “terminated”, “removed”]
The following request illustrates how to retrieve all active subscriptions of a certain customer:
GET /subscriptions?customerId=1000001&status=active
To view details of a certain subscription, send a request with the subscription ID as the suffix of the URL, for example:
GET /subscriptions/1000177 HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16
The response looks similar to the following:
HTTP/1.1 200 OK
{
"id": "1000177",
"customerId": "1000275",
"status": "active",
"renewalStatus": true,
"creationDate": "2019-10-25",
"renewalDate": "2020-10-23",
"lastModifiedDate": "2019-10-25",
"totalPrice": {
"currency": "USD",
"amount": "22.1"
},
"products": [
{
"mpn": "53fc25f7-6639-4f78-bb44-3c2dfec3ed40",
"quantity": "2.0",
"unitPrice": {
"currency": "USD",
"amount": "1.15"
},
"extendedPrice": {
"currency": "USD",
"amount": "2.3"
}
},
{
"mpn": "91fd106f-4b2c-4938-95ac-f54f74e9a239",
"quantity": "1.0",
"unitPrice": {
"currency": "USD",
"amount": "19.8"
},
"extendedPrice": {
"currency": "USD",
"amount": "19.8"
}
}
],
"fulfillmentParameters": [
{
"name": "adminLogin",
"value": "admin@example.onmicrosoft.com"
},
{
"name": "adminPassword",
"value": "F4a[&jsio3"
}
]
}
A sales order can request several products from an offer; all of them will be in the same subscription. If products in the order are from multiple offers, multiple subscriptions will be created, one for each offer referenced.
All operations with subscriptions are initiated by placing certain orders:
Upgrade or downgrade (change limits on products or add more products): Change Order
Renew for the next subscription period: Renewal Order
Cancel: Cancellation Order
When upgrading or downgrading a subscription, you can choose which date to use as subscription period start date after the change: start date of the current subscription period or the date the subscription was changed.
To select the date, add the upgradeStartType
order property with one of these values:
FROM_DATE_OF_UPGRADE (used as the default in billing configuration)
FROM_OLD_START_DATE
For example:
POST /orders HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
Content-Type: application/json
X-Subscription-Key: 066a6b...33b16
{
"customerId": "1012954",
"poNumber": "PO2244",
"type": "change",
"upgradeStartType": FROM_OLD_START_DATE,
"products": [
{
"subscriptionId": "1211331",
"mpn": "SQXAMSENS",
"quantity": "20"
}
]
}
This is the final step in the typical workflow, which results in a customer being subscribed to a product and the provisioning of this product’s services to the customer. Periodically, a reseller needs consolidated data for the commercial activity of the previous period. The next step in the workflow describes how to collect such reports.