Simple API
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.
In this document:
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 SimpleAPI, 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.
Migration Order: migrates a customer’s subscription from an external system.
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
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
}
}
]
}
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.
Placing Sales Order for Microsoft NCE Products¶
To learn which parameters must be in the request when Microsoft NCE products are purchased, refer to this section Parameters.
If you want to place a Sales Order and bypass the Partner Attestation manual checkbox, please see the example of a Sales Order below:
application/json={
"customerId": "1000111111",
"type": "sales",
"ponumber": "00-0000",
"subscriptionPeriod": {
"type": "year",
"duration": 1
},
"products": [
{
"mpn": "CFQ7TTC0LH16:0001",
"quantity": 1,
"billingPeriod": {
"type": "month",
"duration": 1
},
"parameters": [
{
"name": "tenant_preference",
"value": "new"
},
{
"name": "partner_on_record_attestation_accepted",
"structured_value": {
"attestation_accepted": true
}
},
{
"name": "microsoft_domain",
"value": "PlaceDemo1525.onmicrosoft.com"
},
{
"name": "mca_acceptance",
"value": "yes"
},
{
"name": "agreement_date",
"value": "04-09-2022"
},
{
"name": "first_name_agreement",
"value": "John"
},
{
"name": "last_name_agreement",
"value": "Doe"
},
{
"name": "email_address_agreement",
"value": john@doe.com
},
{
"name": "effective_address",
"value": "53 Pendell Road"
},
{
"name": "effective_city",
"value": "Poughkeepsie"
},
{
"name": "effective_state",
"value": "NY"
},
{
"name": "effective_postal_code",
"value": "12601"
},
{
"name": "effective_country",
"value": "US"
},
{
"name": "effective_phonenumber",
"value": "(661) 424-0888"
},
{
"name": "customer_company_name",
"value": "Place Demo"
},
{
"name": "customer_email",
"value": john@doe.com
},
{
"name": "special_qualification",
"value": "none"
},
{
"name": "offer_attestation",
"structured_value": {
"attestation_accepted": false
}
}
]
}
],
}
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.
Migration Order¶
To move a customer’s subscription from an external system to CloudBlue Commerce, you can migrate it by posting a request for a migration order.
Note
Before placing such an order, make sure that the service plan to be bound to the migrated subscription exists because you need to provide its ID in the payload. After placing the order, make sure to take necessary actions to perform provisioning after the subscription is migrated. The time part in the provisioning date of the migrated subscription will be reset to the start of the day.
To specify whether the customer should be billed for the current billing period of the migrated subscription, use the
migrationProgram property with one of the following values:
count_migration_billing_period, customer will be billed for the current billing period fully.do_not_count_migration_billing_period, customer will not be billed for the current billing period.prorate_migration_billing_period, customer will be billed only for the part of current billing period: from the date of migration till the period end.
In the migration order, the migrationDate date must be later than the startDate one.
This is an example of a request for placing a migration order:
POST /orders HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
Content-Type: application/json
X-Subscription-Key: 066a6b...33b16
{
"type":"migration",
"customerId":"1000005",
"products":[
{
"mpn":"SQXAMSENS",
"quantity":"1",
"parameters":[
{
"name":"deal_id",
"value":"42332510"
},
{
"name":"provisioning_contact_name",
"value":"Someone"
},
{
"name":"provisioning_contact_phone",
"value":"1234567890"
},
{
"name":"provisioning_contact_email",
"value":"someone@xyz.com"
},
{
"name":"delayshipdate",
"value":"14/03/2020"
},
{
"name":"web_order_id",
"value":"86598126"
},
{
"name":"vendor_portal_submission",
"value":"NO"
},
{
"name":"vendor_subscription_id",
"value":"RBhhhh2d2d44a6c2812"
}
],
"billingPeriod":{
"type":"month",
"duration":1
}
}
],
"startDate":"2021-06-06",
"migrationDate":"2022-03-29",
"expirationDate":"2022-06-06",
"autorenewal":true,
"migrationProgram":"count_migration_billing_period",
"subscriptionPeriod":{
"type":"year",
"duration":1
},
"planId":"2147147",
"billingModel":"chargeBeforeBillingPeriod"
}
If the order is successfully placed, the response will be similar to the following:
{
"id": "10436379",
"orderNumber": "MO014932",
"type": "migration",
"customerId": "1000005",
"creationDate": "2022-03-29T11:22:35Z",
"status": "processing",
"statusCode": "OP",
"details": [],
"attributes": {
"bill_to": "000",
"PONumber": "N/A",
"reseller_contact_phone": "913235285",
"isresellercentric": "1",
"reseller_contact_name": "JOHN EXAMPLE",
"reseller_contact_email": "JOHN.EXAMPLE@EXAMPLE.COM",
"payment_method": "600"
},
"creditCheck": true,
"products": [
{
"mpn": "SQXAMSENS",
"vendor": "AB-023-329",
"id": "ABC-1803Y8F",
"name": "Sample product name",
"quantity": 1.0,
"subscriptionId": "1079644"
}
]
}
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...33b16
The 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:00Z
Get 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...33b16
The 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.