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 Customers¶
In the platform, a customer is an account (person or organization) that purchases and consumes services provided by its sales vendor. Before requesting a product, the external system that works on behalf of a sales vendor must identify a customer in the platform or create one.
In this document:
The platform exposes operations with its customers on the /customers endpoints.
List Customers¶
To get a list of all customers, the system must send the following request:
GET /customers HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16
If successful, the response looks like this:
HTTP/1.1 200 OK
{
"data": [
{
"id": "1000001",
"externalId": "externalId1",
"name": "RBCustomer",
"status": "active"
},
{
"id": "1000002",
"externalId": "externalId2",
"name": "RBCustomer2",
"status": "active" },
}
],
"pagination": {
"offset": 0,
"limit": 10,
"total": 2
}
}
Create Customers¶
To create a customer, the system must send a POST request with the JSON representation of the customer as in this example:
POST /customers HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16
{
"id": "string",
"externalId": "EXTERNAL-A1S2D3",
"attributes": {
"property1": "string",
"property2": "string"
},
"name": "John Smith",
"externalId": "jsmith101",
"taxRegId": "1357",
"address": {
"streetAddress": "101, Any Street",
"addressExtension": "extension",
"postalCode": "12345",
"city": "Herndon",
"state": "VA",
"countryCode": "US"
},
"contactPersons": [
{
"type": "admin",
"firstName": "John",
"lastName": "Smith",
"email": "js@aps.test",
"phoneNumber": "88##18881234567#"
},
{
"type": "technical",
"firstName": "John",
"lastName": "Smith",
"email": "js@aps.test",
"phoneNumber": "88##18881234567#"
},
{
"type": "billing",
"firstName": "John",
"lastName": "Smith",
"email": "cbdemoisv@aps.test",
"phoneNumber": "88##18881234567#"
}
],
"language": "en"
}
Note
The countryCode property must be the two uppercase character country code (Alpha-2 code) as specified
by ISO.3166-1 .
If successful, the response must look as follows:
HTTP/1.1 200 OK
{
"id": "1000240",
"externalId": "jsmith101",
"attributes": {
"property1": "string",
"property2": "string"
},
"name": "John Smith",
"status": "pending",
"address": {
"streetAddress": "101, Any Street",
"addressExtension": "extension",
"postalCode": "12345",
"city": "Herndon",
"state": "VA",
"countryCode": "US"
},
"contactPersons": [
{
"type": "admin",
"firstName": "John",
"lastName": "Smith",
"email": "js@aps.test",
"phoneNumber": "88##18881234567#"
},
{
"type": "technical",
"firstName": "John",
"lastName": "Smith",
"email": "js@aps.test",
"phoneNumber": "88##18881234567#"
},
{
"type": "billing",
"firstName": "John",
"lastName": "Smith",
"email": "cbdemoisv@aps.test",
"phoneNumber": "88##18881234567#"
}
],
"language": "en"
}
Note
You can specify the login and password of the customer’s admin user when creating a customer.
The customer will be able to use these credentials to access the user control panel.
To do this, add the login and password properties to the contactPerson structure of type admin.
For security reasons, these properties are not returned in a POST or GET response.
For more details, refer to the createCustomer specification.
Get Customer Details¶
To get the full representation of a customer, the system must specify the customer ID as in this example:
GET /customers/1000240 HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16
The response must look as follows:
HTTP/1.1 200 OK
{
"id": "1000240",
"externalId": "jsmith101",
"attributes": {
"property1": "string",
"property2": "string"
},
"name": "John Smith",
"taxRegId": "1357",
"status": "active",
"address": {
"streetAddress": "101, Any Street",
"addressExtension": "extension",
"postalCode": "12345",
"city": "Herndon",
"state": "VA",
"countryCode": "US"
},
"contactPersons": [
{
"type": "admin",
"firstName": "John",
"lastName": "Smith",
"email": "js@aps.test",
"phoneNumber": "88##18881234567#"
},
{
"type": "technical",
"firstName": "John",
"lastName": "Smith",
"email": "js@aps.test",
"phoneNumber": "88##18881234567#"
},
{
"type": "billing",
"firstName": "John",
"lastName": "Smith",
"email": "cbdemoisv@aps.test",
"phoneNumber": "88##18881234567#"
}
],
"language": "en"
}
Update Customers¶
To create a customer, the system must send a PATCH request with the JSON representation of the customer details and specify the customer ID as in this example:
PATCH /customers/100234 HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16
{
"externalId": "EXTERNAL-A1S2D3",
"name": "Acme Inc.",
"taxRegId": "00-0000000",
"address": {
"streetAddress": "555 Main Street",
"addressExtension": "Suite 100",
"postalCode": "92612",
"city": "Irvine",
"state": "CA",
"countryCode": "US"
},
"contactPersons": [
{
"type": "admin",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@email.com",
"phoneNumber": "81##18881234567#",
"login": "someadmin@example.com",
"password": "Ecx$cvdazv"
}
],
"id": "string"
}
The response must look as follows:
HTTP/1.1 200 OK
{
"id": "string",
"externalId": "EXTERNAL-A1S2D3",
"attributes": {
"property1": "string",
"property2": "string"
},
"status": "active",
"name": "Acme Inc.",
"address": {
"streetAddress": "555 Main Street",
"addressExtension": "Suite 100",
"postalCode": "92612",
"city": "Irvine",
"state": "CA",
"countryCode": "US"
},
"contactPersons": [
{
"type": "admin",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@email.com",
"phoneNumber": "81##18881234567#"
}
],
"language": "string",
"taxRegId": "00-0000000",
"resellerId": "string"
}
Conclusion¶
After this phase, the external system has all the necessary data to order selected products for certain customers.