API Documentation

In-depth reference documentation for iQmetrix API's.

NAV

OVERVIEW

The Cart API takes the contents of a completed standard e-commerce shopping cart and submits the cart information to RQ.

The /carts endpoint is used within the context of a specific company, and relative to a specific division, location, device, or other entity represented as a node in the company’s CompanyTree data structure. The identifiers of the company and node must be provided as part of the URI of the request.

The actual shopping cart, including all the items in the cart, is assembled in the client’s e-commerce solution. When the e-commerce cart is ready, it is submitted using the /carts endpoint, to the iQmetrix Cart Service. The Cart Service places the Cart object in a queue, where it is picked up by the Order Service and converted to a Pending Order in the company’s POS system.

It is not possible to update the contents of a cart using this API. The only modification that can be made is to cart status.

BASE URLS

Sandbox: https://cartdemo.iqmetrix.net/v1
Production: https://cart.iqmetrix.net/v1

RESOURCES

Cart

{
    "Id": 987,
    "CompanyId": 14196,
    "EntityId": 14192,
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "jsmith@example.com",
    "PhoneNumber": "555-555-5555",
    "SourceId": "a5bf77f1-bd00-410c-8074-52fd869dc4e8",
    "Status": 2,
    "DateCreatedUtc": "2017-01-10T17:01:12.4580737Z",
    "UpdatedBy": {
        "Id": 59875,
        "FirstName": "iQmetrix",
        "LastName": "Employee"
    },
    "UpdatedUtc": "2017-01-10T17:01:36.5106529Z",
    "Items": [
        {
            "Id": 135,
            "Name": "Galaxy S6 Edge+ 32GB - Black Sapphire",
            "ProductTypeId": 1,
            "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "Slug": "M1248-V1",
            "Quantity": 1,
            "DisplayPrice": 5.99
        }
    ]
}
Name Description
Id (Integer) The identifier of the Cart object. The system generates this identifier when the object is created and returns it in the response to the POST request.
CompanyId (Integer) The identifier of the Company generating the e-commerce cart.
EntityId (Integer) The identifier for the division, location, device, or other entity represented by a node in the Company’s CompanyTree data structure.
FirstName (String) The first name of the customer who created the cart. Maximum 50 characters. If not set, the system sets this value to null.
LastName (String) The last name of the customer who created the cart. Maximum 50 characters. If not set, the system sets this value to null.
Email (String) The email address of the customer who created the cart. The email must be in a valid format. If not set, the system sets this value to null.
PhoneNumber (String) The phone number of the customer who created the cart. Free text: the format is not validated. If not set, the system sets this value to null.
SourceId (GUID) The identifier of the source system submitting the cart information. The only supported source system is Endless Aisle; the identifier for Endless Aisle is provided in your onboarding package.
Status (Integer) An integer representing the cart’s status. Supported values are 1 (New), 2 (Complete), and 3 (Abandoned). Carts are automatically set to Abandoned after 30 minutes of inactivity.
DateCreatedUtc (DateTime) An ISO 8601 UTC timestamp indicating when the cart was created.
UpdatedBy (Object) An object providing information about the user who made the most recent update to the cart. This information is automatically extracted from the update request.
Id (Integer) The identifer of the user who made the update.
FirstName (String) The first name of the user who made the update.
LastName (String) The last name of the user who made the update.
UpdatedUtc (DateTime) An ISO 8601 UTC timestamp indicating when the cart was last updated.
Items (Array[CartItem]) An array of objects representing the items in the cart. For a description of parameters defined for the CartItem resource, see CartItem.

CartItem

{
    "Id": 135,
    "Name": "Galaxy S6 Edge+ 32GB - Black Sapphire",
    "ProductTypeId": 1,
    "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
    "Slug": "M1248-V1",
    "Quantity": 1,
    "DisplayPrice": 5.99
}
Name Description
Id (Integer) The identifier of the CartItem object. The system generates this identifier when the object is created and returns it in the response to the POST request.
Name (String) The name of the item.
ProductTypeId (Integer) The product type identifier. Supported values are 1 (Dropship - the item is available to be drop-shipped) 2 (InStock - The item is in stock) 3 (eCommerce - The item has been submitted by an e-commerce system) and 4 (Shipping - The item has been shipped).
CatalogItemId (String) The identifier of the CatalogItem in the supplier’s catalog.
Slug (String) The URL-compatible, human-readable identifier for the item in the iQmetrix Product Library.
Quantity (Integer) The number of items of this type in the cart.
DisplayPrice (Double) The display price of the item.

REQUESTS

Get All Carts for a Given Entity

Retrieves all shopping carts for a given entity in a company.

Request

GET /companies({CompanyId})/entities({EntityId})/carts

Example Request

GET /companies(14196)/entities(14192)/carts
Authorization: Bearer cn389ncoiwuencr
Accept: application/json

curl -X GET "https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json"
static IRestResponse GetCarts()
{
    var client = new RestClient("https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts");
    var request = new RestRequest(Method.GET);
     
    request.AddHeader("Authorization", "Bearer cn389ncoiwuencr"); 
    request.AddHeader("Accept", "application/json"); 

    

    return client.Execute(request);
}

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;

public static CloseableHttpResponse GetCarts() throws IOException {
    CloseableHttpClient httpClient = HttpClients.createDefault();
    HttpGet request = new HttpGet("https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts");
     
    request.addHeader("Authorization", "Bearer cn389ncoiwuencr"); 
    request.addHeader("Accept", "application/json"); 
    
    return httpClient.execute(request);
}
require 'rest-client'



response = RestClient.get 'https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts', {
     :'Authorization' => 'Bearer cn389ncoiwuencr',
     :'Accept' => 'application/json',
    } 

puts response

Path Parameters

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "Id": 987,
        "CompanyId": 14196,
        "EntityId": 14192,
        "FirstName": "John",
        "LastName": "Smith",
        "Email": "jsmith@texample.com",
        "PhoneNumber": "555-555-5555",
        "SourceId": "a5bf77f1-bd00-410c-8074-52fd869dc4e8",
        "Status": 1,
        "DateCreatedUtc": "2017-01-10T17:21:19.2718560Z",
        "UpdatedBy": "null",
        "UpdatedUtc": "2017-01-10T17:21:19.2718560Z",
        "Items": [
            {
                "Id": 4,
                "Name": "Galaxy S3",
                "ProductTypeId": 2,
                "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
                "Slug": "M5123",
                "Quantity": 2,
                "DisplayPrice": 5.99
            }
        ]
    },
        {
            "Id": 47,
            "CompanyId": 14196,
            "EntityId": 14192,
            "FirstName": "Yuri",
            "LastName": "Kolyakof",
            "Email": "ykolyakof@test.com",
            "PhoneNumber": "4444444444",
            "SourceId": "a5bf77f1-bd00-410c-8074-52fd869dc4e8",
            "Status": 2,
            "DateCreatedUtc": "2017-01-10T14:10:17.6938598",
            "UpdatedBy": {
                "Id": 59875,
                "FirstName": "iQmetrix",
                "LastName": "Employee"
            },
            "UpdatedUtc": "2017-01-10T17:01:36.5106529Z",
            "Items": [
                {
                    "Id": 135,
                    "Name": "Galaxy S6 Edge+ 32GB - Black Sapphire",
                    "ProductTypeId": 1,
                    "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
                    "Slug": "M1248-V1",
                    "Quantity": 1,
                    "DisplayPrice": 5.99
                }
            ]
        }
    ]     

A successful request returns a 200 (OK) response code with the information for all the entity’s carts in the body of the response. For a description of parameters defined for the Cart resource, see Cart.

Get a Single Cart

Retrieves information for a single cart.

Request

GET /companies({CompanyId})/entities({EntityId})/carts({CartId})

Example Request

GET /companies(14196)/entities(14192)/carts(987)
Authorization: Bearer cn389ncoiwuencr
Accept: application/json

curl -X GET "https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts(987)" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json"
static IRestResponse GetACart()
{
    var client = new RestClient("https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts(987)");
    var request = new RestRequest(Method.GET);
     
    request.AddHeader("Authorization", "Bearer cn389ncoiwuencr"); 
    request.AddHeader("Accept", "application/json"); 

    

    return client.Execute(request);
}

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;

public static CloseableHttpResponse GetACart() throws IOException {
    CloseableHttpClient httpClient = HttpClients.createDefault();
    HttpGet request = new HttpGet("https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts(987)");
     
    request.addHeader("Authorization", "Bearer cn389ncoiwuencr"); 
    request.addHeader("Accept", "application/json"); 
    
    return httpClient.execute(request);
}
require 'rest-client'



response = RestClient.get 'https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts(987)', {
     :'Authorization' => 'Bearer cn389ncoiwuencr',
     :'Accept' => 'application/json',
    } 

puts response

Path Parameters

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 987,
    "CompanyId": 14196,
    "EntityId": 14192,
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "test@test.com",
    "PhoneNumber": "5555555555",
    "SourceId": "a5bf77f1-bd00-410c-8074-52fd869dc4e8",
    "Status": 2,
    "DateCreatedUtc": "2017-01-10T17:01:12.4580737Z",
    "UpdatedBy": {
        "Id": 59875,
        "FirstName": "iQmetrix",
        "LastName": "Employee"
    },
    "UpdatedUtc": "2017-01-10T17:01:36.5106529Z",
    "Items": [
        {
            "Id": 135,
            "Name": "Galaxy S6 Edge+ 32GB - Black Sapphire",
            "ProductTypeId": 1,
            "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "Slug": "M1248-V1",
            "Quantity": 1,
            "DisplayPrice": 5.99
        }
    ]
}

A successful request returns a 200 (OK) response code with the information for the cart in the body of the response. For a description of parameters defined for the Cart resource, see Cart.

Search for Carts

Retrieves all carts matching filter criteria.

Request

GET /companies({CompanyId})/entities({EntityId})/carts({CartId})?<query-parameters>

Path Parameters

Query Parameters

Combine filter criteria using the word and; for example, “?filter=Email eq valid@email.com and FirstName eq John”.

When searching on DateCreatedUtc, you can search either on the full timestamp or just on yyyy-mm-dd.

Filter criteria support only eq as a comparison operator, except DateCreatedUtc. DateCreatedUtc supports eq, ge, gte, le, and lte.

Operator Example Interpretation
ge DateCreatedUtc ge 2017-09-01 Created after 2017-09-01
gte DateCreatedUtc gte 2017-09-01 Created on or after 2017-09-01
le DateCreatedUtc le 2017-09-01 Created before 2017-09-01
lte DateCreatedUtc lte 2017-09-01 Created on or before 2017-09-01

Create a Cart

Assembles a Cart resource and submits it to RQ.

Request

POST /companies({CompanyId})/entities({EntityId})/carts

Example Request

POST /companies(14196)/entities(14192)/carts
Authorization: Bearer cn389ncoiwuencr
Accept: application/json
Content-Type: application/json

{
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "test@test.com",
    "PhoneNumber": "5555555555",
    "SourceId": "a5bf77f1-bd00-410c-8074-52fd869dc4e8",
    "Items": [
        {
            "Name": "Galaxy S6 Edge+ 32GB - Black Sapphire",
            "ProductTypeId": 1,
            "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "Slug": "M1248-V1",
            "Quantity": 1,
            "DisplayPrice": 5.99
        }
    ]
}
curl -X POST "https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts" -H "Authorization: Bearer cn389ncoiwuencr" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "test@test.com",
    "PhoneNumber": "5555555555",
    "SourceId": "a5bf77f1-bd00-410c-8074-52fd869dc4e8",
    "Items": [
        {
            "Name": "Galaxy S6 Edge+ 32GB - Black Sapphire",
            "ProductTypeId": 1,
            "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "Slug": "M1248-V1",
            "Quantity": 1,
            "DisplayPrice": 5.99
        }
    ]
}'
static IRestResponse CreateACart()
{
    var client = new RestClient("https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts");
    var request = new RestRequest(Method.POST);
     
    request.AddHeader("Authorization", "Bearer cn389ncoiwuencr"); 
    request.AddHeader("Accept", "application/json"); 
    request.AddHeader("Content-Type", "application/json"); 

     request.AddParameter("application/json", "{\"FirstName\":\"John\",\"LastName\":\"Smith\",\"Email\":\"test@test.com\",\"PhoneNumber\":\"5555555555\",\"SourceId\":\"a5bf77f1-bd00-410c-8074-52fd869dc4e8\",\"Items\":[{\"Name\":\"Galaxy S6 Edge+ 32GB - Black Sapphire\",\"ProductTypeId\":1,\"CatalogItemId\":\"a183f1a9-c58f-426a-930a-9a6357db52ed\",\"Slug\":\"M1248-V1\",\"Quantity\":1,\"DisplayPrice\":5.99}]}", ParameterType.RequestBody);

    return client.Execute(request);
}
import org.apache.http.entity.StringEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;

public static CloseableHttpResponse CreateACart() throws IOException {
    CloseableHttpClient httpClient = HttpClients.createDefault();
    HttpPost request = new HttpPost("https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts");
     
    request.addHeader("Authorization", "Bearer cn389ncoiwuencr"); 
    request.addHeader("Accept", "application/json"); 
    request.addHeader("Content-Type", "application/json"); 
    StringEntity body = new StringEntity("{\"FirstName\":\"John\",\"LastName\":\"Smith\",\"Email\":\"test@test.com\",\"PhoneNumber\":\"5555555555\",\"SourceId\":\"a5bf77f1-bd00-410c-8074-52fd869dc4e8\",\"Items\":[{\"Name\":\"Galaxy S6 Edge+ 32GB - Black Sapphire\",\"ProductTypeId\":1,\"CatalogItemId\":\"a183f1a9-c58f-426a-930a-9a6357db52ed\",\"Slug\":\"M1248-V1\",\"Quantity\":1,\"DisplayPrice\":5.99}]}");
    request.setEntity(body);
    
    return httpClient.execute(request);
}
require 'rest-client'

body = "{\"FirstName\":\"John\",\"LastName\":\"Smith\",\"Email\":\"test@test.com\",\"PhoneNumber\":\"5555555555\",\"SourceId\":\"a5bf77f1-bd00-410c-8074-52fd869dc4e8\",\"Items\":[{\"Name\":\"Galaxy S6 Edge+ 32GB - Black Sapphire\",\"ProductTypeId\":1,\"CatalogItemId\":\"a183f1a9-c58f-426a-930a-9a6357db52ed\",\"Slug\":\"M1248-V1\",\"Quantity\":1,\"DisplayPrice\":5.99}]}";

response = RestClient.post 'https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts', body, {
     :'Authorization' => 'Bearer cn389ncoiwuencr',
     :'Accept' => 'application/json',
     :'Content-Type' => 'application/json',
    } 

puts response

Path Parameters

Request Parameters

Response

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "Id": 987,
        "CompanyId": 14196,
        "EntityId": 14192,
        "FirstName": "John",
        "LastName": "Smith",
        "Email": "test@test.com",
        "PhoneNumber": "5555555555",
        "SourceId": "a5bf77f1-bd00-410c-8074-52fd869dc4e8",
        "Status": 1,
        "DateCreatedUtc": "2017-01-10T17:01:12.4580737Z",
        "UpdatedBy": {
            "Id": 59875,
            "FirstName": "iQmetrix",
            "LastName": "Employee"
        },
        "UpdatedUtc": "2017-01-10T17:01:36.5106529Z",
        "Items": [
            {
                "Id": 135,
                "Name": "Galaxy S6 Edge+ 32GB - Black Sapphire",
                "ProductTypeId": 1,
                "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
                "Slug": "M1248-V1",
                "Quantity": 1,
                "DisplayPrice": 5.99
            }
        ]
    }
]

A successful request returns a 201 (Created) HTTP response with the cart information, including the identifier generated for the new cart. For a description of parameters defined for the Cart resource, see Cart.

Update Cart Status

Updates the status of a cart. Status is the only aspect of a cart that can be updated.

Request

POST /companies({CompanyId})/entities({EntityId})/carts({CartId})/status

Example Request

POST /companies(14196)/entities(14192)/carts(987)/status
Authorization: Bearer cn389ncoiwuencr
Accept: application/json
Content-Type: application/json

{
    "Status": "2"
}
curl -X POST "https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts(987)/status" -H "Authorization: Bearer cn389ncoiwuencr" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
    "Status": "3"
}'
static IRestResponse UpdateCartStatus()
{
    var client = new RestClient("https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts(987)/status");
    var request = new RestRequest(Method.POST);
     
    request.AddHeader("Authorization", "Bearer cn389ncoiwuencr"); 
    request.AddHeader("Accept", "application/json"); 
    request.AddHeader("Content-Type", "application/json"); 

     request.AddParameter("application/json", "{\"Status\":\"3\"}", ParameterType.RequestBody);

    return client.Execute(request);
}
import org.apache.http.entity.StringEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;

public static CloseableHttpResponse UpdateCartStatus() throws IOException {
    CloseableHttpClient httpClient = HttpClients.createDefault();
    HttpPost request = new HttpPost("https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts(987)/status");
     
    request.addHeader("Authorization", "Bearer cn389ncoiwuencr"); 
    request.addHeader("Accept", "application/json"); 
    request.addHeader("Content-Type", "application/json"); 
    StringEntity body = new StringEntity("{\"Status\":\"3\"}");
    request.setEntity(body);
    
    return httpClient.execute(request);
}
require 'rest-client'

body = "{\"Status\":\"1\"}";

response = RestClient.post 'https://cartdemo.iqmetrix.net/v1/companies(14196)/entities(14192)/carts(987)/status', body, {
     :'Authorization' => 'Bearer cn389ncoiwuencr',
     :'Accept' => 'application/json',
     :'Content-Type' => 'application/json',
    } 

puts response

Path Parameters

Request Parameters

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 987,
    "CompanyId": 14196,
    "EntityId": 14192,
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "test@test.com",
    "PhoneNumber": "5555555555",
    "SourceId": "a5bf77f1-bd00-410c-8074-52fd869dc4e8",
    "Status": 2,
    "DateCreatedUtc": "2017-01-10T17:01:12.4580737Z",
    "UpdatedBy": {
        "Id": 59875,
        "FirstName": "John",
        "LastName": "Bates"
    },
    "UpdatedUtc": "2017-01-10T17:01:36.5106529Z",
    "Items": [
        {
            "Id": 135,
            "Name": "Galaxy S6 Edge+ 32GB - Black Sapphire",
            "ProductTypeId": 1,
            "CatalogItemId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "Slug": "M1248-V1",
            "Quantity": 1,
            "DisplayPrice": 5.99
        }
    ]
}

Cart

ERRORS

Error Code Name Description
HTTP 400 Bad Request The request was somehow incorrect or invalid. Check that the FirstName and LastName do not exceed 50 characters, and that Email is in a valid format.
HTTP 401 Unauthorized The user making the request is not authenticated. The most common reason for this is that the access token used in the request has expired. Generate a new access token (or refresh the existing token) using the Authentication API.
HTTP 403 Forbidden The user making the request is authenticated, but does not have permission to access the requested resource. Make sure that the user making the request has appropriate permissions.
HTTP 404 Not Found The requested resource cannot be found. Ensure that the request URI is correct and that the correct method has been used.
Was this page helpful?