Marketplace API
Note
On November 15th, 2021 Ingram Micro has updated Marketplace API on production, which has changed the way the API behaves in some cases. It is imperative that you read the Marketplace API 1.6 release notes carefully, modify your integrations (API clients) to match the updated specifications, and prepare to update your API clients at the time when the new version is implemented by Ingram Micro.
The documentation for the new version can be found under https://apidocs.cloud.im/1.6/. After November 15th, this documentation portal will automatically display this new version.
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 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...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.