Overview

This guide is intended to walk you through the process of creating an Order that is fulfilled in a store (not dropship or eCommerce).

Creating an Order will make it available to other iQmetrix products such as RQ and Endless Aisle.

Postman Example

iQmetrix uses Postman when testing and debugging our APIs.

For Chrome or Mac users, click the button below to import the collection directly into Postman.

Who Is This Guide For?

You may be interested in this guide if you are creating…

Prerequisites

To use this guide, the following steps must be completed:

If the above steps are not complete or you are not sure, contact Support.

Before You Begin

Before you can create an Order, you will need to know:

Steps

Step 1 - Authenticating

In order call iQmetrix APIs, we first need an Access Token.

See the table below for different ways of getting an Access Token.

If… Then…
You do not have an Access Token See Obtaining an Access Token
You have an Access Token, but it is close to expiring See Refreshing an Access Token

The token is placed in the Authorization header of requests to iQmetrix APIs, prefixed by the word Bearer.

Example
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Step 2 - Finding or Creating a Location

Every Order must have an associated Location that belongs to a Company.

We will reference this Location in our request by using its EntityId.

For the Order to appear in the pending list of orders in RQ, the EntityId must match the EntityId of the logged-in store.

If… Then…
You know basic store details but not the EntityId See Getting All Locations for a Company
Location does not exist in the system See Creating a Location
Example
"EntityId": 14192

Step 3 - Finding or Creating a Customer

Every Order must have an associated Customer that belongs to the Company.

We will reference this Customer in our request by using its CustomerId.

If… Then…
You know the Customer’s address or phone number See Customer Search
Customer exists in the system but needs to be updated See Updating a Customer
Customer does not exist in the system See Creating a Customer
Example
"BillingCustomerId": "659c2a38-d083-4421-9330-46d779702f85"

It is optional but recommended to include a billing Address for the Customer in the request.

We will reference this Address in our request by using its AddressId.

If… Then…
You have the BillingCustomerId from Step 4 See Getting a Full Customer and select the AddressId of the appropriate Address
You know the name or street address of the Customer See Customer Search to find the Customer and obtain the appropriate AddressId
Customer does not have a billing address See Adding a Customer Address
Example
"BillingAddressId": "a08b0640-606a-41f0-901a-facaf50e75dd"

Step 5 - Setting the Order Type

Each Order must have an associated OrderType.

There are many different OrderTypes. We will use the Sales type for an in-store Order, referencing it by associated identifier 1.

Example
"OrderTypeId": 1

(Optional) Step 6 - Adding Optional Order Properties

The following Order properties can be added to the request:

Example
"Name": "Interactive Display Order 331", 
"DiscountAmount": 15.0,
"DiscountCode": "MTRY-15",
"DiscountDescription": "Military discount",
"OrderExpiryHours": 72

Step 7 - Getting a Catalog Item

Example
"ProductId": "a183f1a9-c58f-426a-930a-9a6357db52ed"

Step 8 - Setting the Item Type

Each Order Item on the Order must have an associated Item Type in the form of an integer.

For an in-store order, we will use the InStock ItemType which has a value of 2.

Example
"ItemTypeId": 2

For each Product we want to add to our Order, we first need to find it in our Catalog, which contains store(s) inventory.

We will reference the Product(s) in our request by using a CatalogItemId as the value for the ProductId request parameter.

If… Then…
You have a CatalogItemId but are unsure if it belongs to your Product Confirm by Getting Product Details
You know the Product’s Name, Manufacturer Name, UPC, or SKU See Searching for Products
The Product does not exist in your Catalog Contact API Support. to have the Product added to your Catalog

Step 9 - Setting the Item Status

Example
"ItemStatusId": 9

(Optional) Step 10 - Adding Optional Item Properties

Each Order Item added to the Order may also have the following optional properties:

Example
"Description": "LG G3 phone case",
"Index": 1,
"Notes": "",
"Quantity": 2,
"SerialNumbers": ["EQE0RCHD"]

Each Item Type on the Order must have an associated Item Status value in the form of an integer.

Options for ItemStatus are determined by the ItemType chosen in Step 2.

For RQ to accept the Item, the ItemStatus must be New, or a value of 9.

Step 11 - Creating the Order

We can now combine the information gathered in previous steps to Create an Order with Items.

Example Request
POST /Companies(14146)/OrderFull
Authorization: Bearer (Access Token)
Accept: application/json
Content-Type: application/json
{
    "OrderTypeId": 1,
    "EntityId": 14192,
    "BillingCustomerId": "659c2a38-d083-4421-9330-46d779702f85",
    "Name": "Interactive Display Order 331", 
    "OrderExpiryHours": 72,
    "BillingAddressId": "a08b0640-606a-41f0-901a-facaf50e75dd",
    "DiscountAmount": 15.0,
    "DiscountCode": "MTRY-15",
    "DiscountDescription": "Military discount",
    "Items": [
        {
            "ItemStatusId": 9,
            "ItemTypeId": 2,
            "ProductId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "Description": "LG G3 phone case",
            "Notes": "",
            "Quantity": 2,
            "SerialNumbers":  ["EQE0RCHD"]
        }
    ]
}

Example Response

Note that some fields are omitted from the response as they are not relevant to this guide.

HTTP 201 Content-Type: application/json
{
    "Id": "902cdc91-65f4-4c7d-b336-5f291849f2fe",
    "Name": "Interactive Display Order 331", 
    "EntityId": 14192,
    "State": "Created",
    "OrderExpiryDate": "2015-05-08T18:05:13.137",
    "OrderExpiryHours": 72,
    "OrderType": "Sales",
    "OrderTypeId": 1,
    "CreatedDateUtc": "2015-05-05T18:05:13.137",
    "BillingAddressId": "a08b0640-606a-41f0-901a-facaf50e75dd",
    "BillingCustomerId": "659c2a38-d083-4421-9330-46d779702f85",
    "DiscountCode": "MTRY-15",
    "DiscountDescription": "Military discount",
    "DiscountAmount": 15.0,
    "PrintableId": "8765-1234-987"
    "Items": [
        {
            "Id": "2ad88692-7757-4a72-915b-dfe8f2539279",
            "OrderId": "902cdc91-65f4-4c7d-b336-5f291849f2fe",
            "ItemStatus": "New",
            "ItemStatusId": 9,
            "ItemTypeId": 2,
            "ProductId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "Description": "LG G3 phone case",
            "Notes": "",
            "Quantity": 2,
            "SerialNumbers":  ["EQE0RCHD"]
        }
    ]
}

Next Steps

Now that you have created an Order, you may be interested in:

Troubleshooting

If you encounter any errors while following this guide, see Order Errors

Was this page helpful?