The API is structured around REST in a simplified form. The API uses predictable operations-oriented URLs.
This API reference is for API version 2. This is the most recent version.
This API should be contacted via HTTPS only for security reasons.
The authentication header must include Bearer followed by a base64-encoded signed token. Generation of the token is described in a separate section.
curl -H "authorization: Bearer token"
You will have received a username from us as part of the setup process. Your username will form part of the URL for all end-points. In the examples below your username is represented by username.
The following scopes are currently supported:
URL:
GET https://store_url/api/v2/username/order/?
Header:
Authorization : Bearer token
Token
{
"password": yourpassword
}
| Name | Value |
|---|---|
| id |
A URL encoded string consisting of a single order ID or multiple order IDs separated by comma. Examples (URL encoded): id=100 id=100%2C101%2C102 (ie. 100,101,102) |
| new |
Selects for orders not previously exported via API. Can be combined with other parameters. Value: 'true' Example: new=true |
| status |
A URL encoded string consisting of a single order status ID or multiple order status IDs separated by comma. Please discuss with us which different order statuses are used in your store for pending orders, completed orders, cancelled orders etc. Examples (URL encoded): status=4 status=4%2C5%2C6 (ie. 4,5,6) |
| id_from |
A URL encoded string consisting of a single order ID. The API will return orders from and including the requested ID. Example: id_from=100 |
| id_to |
A URL encoded string consisting of a single order ID. The API will return orders up to and including the requested ID. Example: id_to=110 |
| date_from |
A URL encoded string consisting of a single date and time in the specified format. The API will return orders from and including the requested datetime. Format: YYYYMMDDHHMNSS where YYYY - year, MM = month, DD = day, HH = hour, MN = minute and SS = seconds, in 24-hour format. Example: date_from=20241214000000 (logic equivalent of datetime>=20241214000000. December 14 2024 at midnight, which captures all orders placed on December 14 onwards). |
| date_to |
A URL encoded string consisting of a single date and time in the specified format. The API will return orders up to but not including the requested datetime. Format: YYYYMMDDHHMNSS where YYYY - year, MM = month, DD = day, HH = hour, MN = minute and SS = seconds, in 24-hour format. Example: date_to=20241215000000 (logic equivalent of datetime<20241215000000. Up to December 15 2024 at midnight, which captures all orders placed on the previous date, December 14, but no orders dated December 15). |
| customer_company |
A URL encoded string consisting of a single company name, matching the company name recorded on the order. The name is not case sensitive. |
| customer_phone |
A URL encoded string consisting of a single number, matching the phone number recorded on the order. |
| customer_email |
A URL encoded string consisting of a single email address, matching the email address recorded on the order. |
| sku | A URL encoded string consisting of one or more SKUs separated by comma. The API will return orders where at least one of the provided SKUs match a line in the order. |
Responses are json encoded. Below we will first provide an overview of the response structures before providing the data structure of orders:
| result | text |
|---|---|
| Incorrect values |
If the API encounters incorrect values in a parameter, the following error will be returned, specifying hte parameter in question: {
"info": "There is a problem with the value of date_from"
}
|
| Unmatched orders |
If you are requesting a number of specific IDs together with additional parameters and some of the specific order IDs do not match all the parameters, then we will list an array of the unmatched order IDs before listing the matching orders like so: {
"unmatched_orders": [
{
"id": "105"
},
{
"id": "108"
}
],
|
| No matched orders |
If no orders matched the requests, then the response will always be like so: {
"info": "No orders were found matching the request"
}
|
| Orders |
Orders are listed as an array. Each order consists of the following elements (example given below):
id contains the order ID as an integer. orderinfo contains basic order details. The following array is returned:
billto contains billing information. The following array is returned:
shipto contains shipping address. The following array is returned:
lineitems Multiple line items will be returned in an array, including one for each product line and one for each of any shipping charges, discounts, fees etc that may be included in the order. Each lineitem contains the following array:
Example structure of 2 orders, each with 2 lineitems:
{
"orders": [
{
"id": "100",
"orderinfo": {
"source_url": "",
"order_status": "",
"credit_status": "",
"order_datetime": "",
"order_customer_id": "",
"order_ponumber": "",
"LineAmountTypes": ""
},
"billto": {
"name": "",
"company": "",
"address": "",
"address_line2": "",
"city": "",
"postcode": "",
"region": "",
"country": "",
"phone": "",
"email": ""
},
"shipto": {
"name": "",
"company": "",
"address": "",
"address_line2": "",
"city": "",
"postcode": "",
"region": "",
"country": ""
},
"lineitems": [
{
"description": "",
"sku": "",
"quantity": "",
"unitamount": "",
"accountcode": "",
"taxtype": "",
"taxamount": ""
},
{
"description": "",
"sku": "",
"quantity": "",
"unitamount": "",
"accountcode": "",
"taxtype": "",
"taxamount": ""
}
]
},
{
"id": "101",
"orderinfo": {
"source_url": "",
"order_status": "",
"credit_status": "",
"order_datetime": "",
"order_customer_id": "",
"order_ponumber": "",
"LineAmountTypes": ""
},
"billto": {
"name": "",
"company": "",
"address": "",
"address_line2": "",
"city": "",
"postcode": "",
"region": "",
"country": "",
"phone": "",
"email": ""
},
"shipto": {
"name": "",
"company": "",
"address": "",
"address_line2": "",
"city": "",
"postcode": "",
"region": "",
"country": ""
},
"lineitems": [
{
"description": "",
"sku": "",
"quantity": "",
"unitamount": "",
"accountcode": "",
"taxtype": "",
"taxamount": ""
},
{
"description": "",
"sku": "",
"quantity": "",
"unitamount": "",
"accountcode": "",
"taxtype": "",
"taxamount": ""
}
]
}
]
}
|
| Unmatched and matched orders, full example |
As mentioned above, with specific order IDs requested, there will be a listing of unmatched order IDs, like so:
{
"unmatched_orders": [
{
"id": "105"
},
{
"id": "108"
}
],
"orders": [
{
"id": "100",
"orderinfo": {
"source_url": "",
"order_status": "",
"credit_status": "",
"order_datetime": "",
"order_customer_id": "",
"order_ponumber": "",
"LineAmountTypes": ""
},
"billto": {
"name": "",
"company": "",
"address": "",
"address_line2": "",
"city": "",
"postcode": "",
"region": "",
"country": "",
"phone": "",
"email": ""
},
"shipto": {
"name": "",
"company": "",
"address": "",
"address_line2": "",
"city": "",
"postcode": "",
"region": "",
"country": ""
},
"lineitems": [
{
"description": "",
"sku": "",
"quantity": "",
"unitamount": "",
"accountcode": "",
"taxtype": "",
"taxamount": ""
},
{
"description": "",
"sku": "",
"quantity": "",
"unitamount": "",
"accountcode": "",
"taxtype": "",
"taxamount": ""
}
]
},
{
"id": "101",
"orderinfo": {
"source_url": "",
"order_status": "",
"credit_status": "",
"order_datetime": "",
"order_customer_id": "",
"order_ponumber": "",
"LineAmountTypes": ""
},
"billto": {
"name": "",
"company": "",
"address": "",
"address_line2": "",
"city": "",
"postcode": "",
"region": "",
"country": "",
"phone": "",
"email": ""
},
"shipto": {
"name": "",
"company": "",
"address": "",
"address_line2": "",
"city": "",
"postcode": "",
"region": "",
"country": ""
},
"lineitems": [
{
"description": "",
"sku": "",
"quantity": "",
"unitamount": "",
"accountcode": "",
"taxtype": "",
"taxamount": ""
},
{
"description": "",
"sku": "",
"quantity": "",
"unitamount": "",
"accountcode": "",
"taxtype": "",
"taxamount": ""
}
]
}
]
}
|