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 for testing and debugging our APIs.
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…
- A system to manage service requests
- A mobile POS that will send Orders to RQ
- An Interactive solution allowing users to add items to an order, which is then picked up by RQ to be processed
Prerequisites
To use this guide, the following steps must be completed:
- You must have your onboarding package from iQmetrix, which includes your access credentials and environments
- Your Product Library, or physical inventory for your store(s), must be set up
- Your Company Tree, representing company structure (stores, groups, divisions, etc), must be created
Before You Begin
To make requests to iQmetrix APIs, you must generate an Access Token.
Use the request Obtaining an Access Token and the following parameters:
grant_type
- Usepassword
client_id
- Provided in Onboarding Packageclient_secret
- Provided in Onboarding Packageusername
- Provided in Onboarding Packagepassword
- Provided in Onboarding Package
Example Request (cURL)
curl -X POST \
https://accountsdemo.iqmetrix.net/v1/oauth2/token \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=password&client_id=PROVIDEDCLIENTID&client_secret=PROVIDEDSECRET&username=EMAIL&password=PASSWORD'
Example Response
HTTP 200
{
"access_token": "b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz",
"expires_in": 43199,
"refresh_token": "FOPAB0K3eshQjrJW4mt6FbWF3OwDJL7CGdZX"
}
The token (access_token
) is placed in the Authorization
header of requests to iQmetrix APIs, prefixed by the word Bearer
.
Example
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Steps
Step 1 - Finding or Creating a Location
Every Order must have an associated that belongs to the .
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 2 - Finding or Creating a Customer
Every must have an associated that belongs to the .
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"
Step 3 - Finding or Creating a Billing Address
All orders must include a billing for the in the request.
We will reference this Address in our request by using its AddressId
.
If… | Then… |
---|---|
You have the BillingCustomerId from Step 2 | 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 4 - Setting the Order Type
Each must have an associated OrderType.
We will use the Sales
type for an in-store Order, referencing it by associated identifier 1
.
Example
"OrderTypeId": 1
(Optional) Step 5 - Adding Optional Order Properties
The following properties can be added to the request:
Name
- Name of the OrderDiscountAmount
- Value of discount to be applied at Order levelDiscountCode
- Discount Code for a discount applied to this OrderDiscountDescription
- Description of the discountOrderExpiryHours
- Amount of time in hours before the Order expires, defaults to 72. When the Order expires it will be removed from the pending list of orders in RQ upon refresh
Example
"Name": "Interactive Display Order 331",
"DiscountAmount": 15.0,
"DiscountCode": "MTRY-15",
"DiscountDescription": "Military discount",
"OrderExpiryHours": 72
Step 6 - Getting a Catalog Item
For each Product we want to add to our , 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 |
Example
"ProductId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
Step 7 - Setting the Item Type
Each Order Item on the Order must have an associated ItemType 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
Step 8 - Setting the Item Status
Each Item on the Order must have an associated ItemStatus value in the form of an integer.
Options are determined by the ItemType chosen in Step 7.
For RQ to accept the Item, the ItemStatus must be New
, or a value of 9
.
Example
"ItemStatusId": 9
(Optional) Step 9 - Adding Optional Item Properties
Each Order Item added to the Order may also have the following optional properties:
Description
- Description of this ItemIndex
- A value used for sorting, if you wish to change the order of the Items on the invoice in RQ. If omitted, this value will be automatically generatedNotes
- Free form text holding notes to be stored with this ItemQuantity
- Amount of this Item in stock, defaults to 0SerialNumbers
- Product serial numbers
Example
"Description": "LG G3 phone case",
"Index": 1,
"Notes": "",
"Quantity": 2,
"SerialNumbers": ["EQE0RCHD"]
Step 10 - 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 b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
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
Response is truncated for brevity.
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 Errors.