Manage Orders
To subscribe a customer to products, the external system must place an order for those products. After the order is paid, the requested services are provisioned in the scope of the new subscription created for that customer.
The platform exposes operations with its orders on the /orders endpoints.
Place Orders
In the platform, orders are used to perform certain operations with subscriptions. Through the CMP API, you can operate the following orders:
Sales Order: creates a subscription for specified products. A subscription is created for a customer during the order provisioning and is valid during a subscription period (a number of months or years as specified in the respective service plan).
Change Order: upgrades or downgrades a specified subscription. Correspondingly, it increases or decreases the limits on product units that the subscriber can use.
Renewal Order: renews a specified subscription for the next subscription period.
Cancellation Order: cancels a specified subscription.
Note
If you place the order for a product with a non-unique MPN (for example, if the MPN is duplicated in the product catalog), the error message in response will contain the explanation that you need to provide additional parameters. Therefore, you must provide more parameters in the request to identify such product. The following parameters are used to identify a product (from the most to least important): mpn, vendor, subscriptionPeriod, billingPeriod. See the example below:
{
"customerId": "1012954",
"poNumber": "myponumber"
"type": "sales",
"products": [
{
"mpn": "bd938-058f-4927-bba3-ae36b1d2501c",
"vendor": "somevendor",
"billingPeriod": {
"type": "month",
"duration": 1
},
"subscriptionPeriod": {
"type": "year",
"duration": 1
}
}
]
}Sales Order
To subscribe a customer to products, the external system must place a sales order containing the customer ID and a list of products (with limits on the number of product units - quantity) as in this example:
POST /orders/ HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
Content-Type: application/json
X-Subscription-Key: 066a6b...33b16
{
"type": "sales",
"customerId": "1000001",
"poNumber": "myponumber",
"products": [
{
"mpn": "53fc25f7-6639-4f78-bb44-3c2dfec3ed40",
"quantity": "2.0"
},
{
"mpn": "91fd106f-4b2c-4938-95ac-f54f74e9a239",
"quantity": "1.0",
"parameters": [
{
"name": "domain",
"value": "jsmith201"
}
]
}
]
}Note
When ordering a bunch of products, ensure that the order contains products from only one service plan (offer). You can identify an offer by the serviceName property in the product list.
If successful, the response looks like this:
HTTP/1.1 200 OK
{
"id": "1000001",
"type": "sales",
"customerId": "1000001",
"creationDate": "2019-09-02T06:26:08Z",
"status": "processing"
}All requested products of an offer will be in the same subscription.
Note
The format of a response on placing other order types is the same. For this reason, the other responses are no longer displayed in this document.
Change Order
Change orders enable you to change product units in a specified subscription:
Add more products
Increase (upgrade) or decrease (downgrade) limits on product units
Similar to sales orders, the limits on product units in a change order are the final values to be set in the subscription. For example, if the current limit on a product’s units in a subscription is 10 and you want to change it to 20, the change order must have quantity equal 20 in the change order for this product:
POST /orders HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
Content-Type: application/json
X-Subscription-Key: 066a6b...33b16
{
"customerId": "1012954",
"poNumber": "PO2244",
"type": "change",
"products": [
{
"subscriptionId": "1211331",
"mpn": "SQXAMSENS",
"quantity": "20"
}
]
}If you need to remove a product from a subscription, make its quantity zero in this subscription.
Renewal Order
To renew a subscription for the next period, place a renewal order as in the following example:
POST /orders/ HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
Content-Type: application/json
X-Subscription-Key: 066a6b...33b16
{
"customerId": "1012954",
"poNumber": "PO2244",
"type": "renewal",
"products": [
{
"subscriptionId": "1211330"
}
]
}If successful, the subscription expiration date will be moved forward by the subscription period as configured in the offer.
Cancellation Order
When a subscription is no longer necessary, you can cancel it by posting a request for a cancellation order, 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": "cancellation",
"products": [
{
"subscriptionId": "1211331"
}
]
}A cancellation order stays in the submitted status until you approve it manually in the reseller control panel. After that, the subscription is terminated.
Update Orders
The ability to update an order is limited to a single property creditCheck. You can modify it to enable or disable checks of the customer’s credit. To update an order, the requester must specify the order ID in the request and provide the following content:
PATCH /orders/100230 HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
Content-Type: application/json
X-Subscription-Key: 066a6b...33b16
{
"creditCheck": true
}The response looks similar to the following:
HTTP/1.1 200 OK
{
"id": "string",
"orderNumber": "SO000012",
"type": "sales",
"customerId": "string",
"poNumber": "PO1234",
"creationDate": "2019-08-24T14:15:22Z",
"status": "submitted",
"statusCode": "CP",
"total": {
"currency": "USD",
"amount": "70.5"
},
"products": [
{
"mpn": "d903a2db-bf6f-4434-83f1-21ba44017813_ANNUAL",
"id": "sku-d903a2db-bf6f-4434-83f1-21ba44017813",
"billingPeriod": {
"type": "month",
"duration": 0
},
"newMPN": "string",
"newId": "string",
"name": "Office 365 Enterprise E1",
"quantity": 10,
"extendedPrice": {
"currency": "USD",
"amount": "70.5"
},
"specialPrice": {
"currency": "USD",
"amount": "70.5"
},
"specialCost": {
"currency": "USD",
"amount": "70.5"
},
"specialProviderCost": {
"currency": "USD",
"amount": "70.5"
},
"subscriptionId": "string",
"parameters": [
{
"name": "domain",
"value": "example.com"
}
]
}
],
"details": [
{
"type": "recurring",
"mpn": "d903a2db-bf6f-4434-83f1-21ba44017813_ANNUAL",
"productId": "sku-d903a2db-bf6f-4434-83f1-21ba44017813",
"duration": {
"type": "month",
"duration": 1
},
"description": "Recurring for the product",
"quantity": 5,
"unitPrice": {
"currency": "USD",
"amount": "70.5"
},
"extendedPrice": {
"currency": "USD",
"amount": "70.5"
},
"discount": {
"type": "percent",
"value": "0.5",
"amount": "25.0"
},
"taxAmount": {
"currency": "USD",
"amount": "70.5"
},
"exclusiveTaxAmount": {
"currency": "USD",
"amount": "70.5"
}
}
],
"attributes": {
"property1": "string",
"property2": "string"
},
"creditCheck": true,
"autorenewal": true,
"startDate": "2020-10-30T00:00:00.000Z",
"expirationDate": "2020-10-30T00:00:00.000Z",
"lastBillingDate": "2020-10-30T00:00:00.000Z",
"nextBillingDate": "2020-10-30T00:00:00.000Z",
}List Orders
An API client can get the full list of orders or narrow down the returned list by adding certain search criteria to a request.
List All Orders
To get the full list of orders, send this request:
GET /orders?customerId=1000275 HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16The response looks similar to the following:
HTTP/1.1 200 OK
{
"data": [
{
"id": "1001042",
"type": "sales",
"customerId": "1000275",
"creationDate": "2019-10-25T09:52:54Z",
"status": "error"
},
{
"id": "1001044",
"type": "sales",
"customerId": "1000275",
"creationDate": "2019-10-25T10:06:17Z",
"status": "completed"
}
],
"pagination": {
"offset": 0,
"limit": 10,
"total": 2
}
}List Selected Orders
The returned list of orders is narrowed down by the following query parameters:
customerId: the ID of the order owner that is a customer (also known as a subscriber)status: the order status (“draft”, “processing”, “error”, “complete”, or “cancelled”)subscriptionId: the ID of the related subscriptioncreationTimeFrom: the beginning of a specific period of time used to search for orders created during that same periodcreationTimeTo: the end of a specific period of time used to search for orders created during that same period
The following request illustrates the use of all the above query parameters:
GET
/orders?customerId=1000001&status=complete&subscriptionId=1000054&creationTimeFrom=2019-10-01T03:00:00Z&creationTimeTo=2019-12-17T03:00:00ZGet Order Details
To get details of an order, the requester must specify the order ID in the request as in this example:
GET /orders/1001044 HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16The response looks similar to the following:
HTTP/1.1 200 OK
{
"id": "1001044",
"type": "sales",
"customerId": "1000275",
"creationDate": "2019-10-25T10:06:17Z",
"status": "completed",
"products": [
{
"mpn": "53fc25f7-6639-4f78-bb44-3c2dfec3ed40",
"name": "Office 365 Extra File Storage",
"quantity": "2.0",
"extendedPrice": {
"currency": "USD",
"amount": "2.3"
},
"subscriptionId": "1000177"
},
{
"mpn": "91fd106f-4b2c-4938-95ac-f54f74e9a239",
"name": "Office 365 Enterprise E1",
"quantity": "1.0",
"extendedPrice": {
"currency": "USD",
"amount": "19.8"
},
"subscriptionId": "1000177"
}
]
}Price Estimation
The API allows you to estimate the total price and price components of an order before placing that same real order. A request looks the same as a request for placing an order as in the following example:
POST /orders/estimate HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
Content-Type: application/json
X-Subscription-Key: 066a6b...33b16
{
"customerId": "1012954",
"type": "sales",
"products": [
{
"mpn": "53fc25f7-6639-4f78-bb44-3c2dfec3ed40",
"quantity": "2.0"
},
{
"mpn": "91fd106f-4b2c-4938-95ac-f54f74e9a239",
"quantity": "1.0"
}
]
}The response contains the total order price and its components:
HTTP/1.1 200 OK
{
"total": {
"currency": "AUD",
"amount": "22.1"
},
"products": [
{
"mpn": "53fc25f7-6639-4f78-bb44-3c2dfec3ed40",
"quantity": "2.0",
"price": {
"currency": "USD",
"amount": "1.15"
}
},
{
"mpn": "91fd106f-4b2c-4938-95ac-f54f74e9a239",
"quantity": "1.0",
"price": {
"currency": "USD",
"amount": "19.8"
}
}
]
}An estimation is available for Sales, Change, Renewal, and Cancellation orders.
Limitations
Single Subscription
An order manages only one subscription. However, you can place a sales order to purchase products from different offers (service plans), which will create several subscriptions.
Order Type Dependence
An order request body contains the following properties in an element of the products array depending on the order type:
Property | Sales | Change | Renewal | Cancellation |
|---|---|---|---|
| Required | Required | Not used |
| Not used | Required | Required |
Quantities in Change Orders
When requesting a new limit for a product in a certain subscription, a change order must contain that same limit as the product quantity. However, when you request the order details after it is completed, you will find the difference between the quantity after the change is completed and its initial value. For example, if the initial quantity was 2 and you requested 22 in a change order, in the response for the order details you will find 20.
Special Prices
There are the following limits on the use of special prices:
Special pricing only works when placing or estimating sales orders. It does not work with other order types.
In every product within an order, the price must contain only one component; this is usually a recurring fee.
To use the
specialProviderCostproperty, the privilege Application Order Management: Allow to place orders with spot provider costs must be enabled for the user authenticated in the corresponding API call. For security configuration, open the OSS provider control panel, navigate to System > Settings, and then follow the Security link.
Conclusion
After this phase, your customers are subscribed to the selected products. The reseller’s system continues managing the created subscriptions as described in the next phase.