Orders API

API reference

The API is structured around REST in a simplified form. The API uses predictable operations-oriented URLs.

API version

This API reference is for API version 2. This is the most recent version.

Protocol

This API should be contacted via HTTPS only for security reasons.

API authentication

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"

Username

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.

API scopes

The following scopes are currently supported:

  • Order

Request

URL:
GET https://store_url/api/v2/username/order/?

Header:
Authorization : Bearer token

 

Token

First you create a json encoded string containing your password:
{
  "password": yourpassword
}
This string is then signed/encrypted using your private key, which you will have received from us.
The result is then base64 encoded before being added to the Authentication header.
 
Request parameters
The following request parameters are supported. The parameters can be combined. At least one parameter is required.
Note that parameters must be URL encoded.
 
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.
Request string examples
URL:
GET https://store_url/api/v2/username/order/?id=100%2C101%2C102

GET https://store_url/api/v2/username/order/?status=4&date_from=20241214000000&date_to=20241215000000&customer_email=test%40test.com

GET https://store_url/api/v2/username/order/?date_from=20241214093000

Response structures

Responses are json encoded. Below we will first provide an overview of the response structures before providing the data structure of orders:

result text
Timestamp

Each response includes a timestamp. This can be used to get all order since your last request by using this timestamp in the date_from request parameter.

Format:

YYYYMMDDHHMNSS

where YYYY - year, MM = month, DD = day, HH = hour, MN = minute and SS = seconds, in 24-hour format.

{
  "timestamp": "20241214221500"
}
Connection, authentication and authorization errors

If the API encounters connection errors or erros authenticating or authorizing the request, the arror message will be returned:

{
  "timestamp": "20241214221500",
  "info": "There is a problem with the value of date_from"
} 

Possible values:

  • Blocked IP
  • IP address not approved
  • API not available
  • Not verified (bearer authorization missing)
  • API user missing from request
  • API user not authorized
  • Request not authorized
  • Incorrect API user or password
  • Could not decrypt token, incorrect key
  • Resource type not set or available
  • There was an error processing the request

 
Incorrect request parameter values

If the API encounters incorrect values in a parameter, the following error will be returned, specifying the parameter in question:

{
  "timestamp": "20241214221500",
  "info": "There is a problem with the value of date_from"
}

 Possible values:

  • No parameters found in request
  • No orders were found matching the request
  • There is a problem with the value of id
  • There is a problem with the value of status
  • There is a problem with the value of id_from
  • There is a problem with the value of id_to
  • There is a problem with the value of date_from
  • There is a problem with the value of date_to
Unmatched requested 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:

{
  "timestamp": "20241214221500",
  "unmatched_orders": [
    {
      "id": "105"
    },
    {
      "id": "108"
    }
  ],
  "orders": [
etc
No matched orders

If no orders matched the requests, then the response will always be like so:

{
  "timestamp": "20241214221500",
  "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
  • orderinfo
  • billto
  • shipto
  • lineitems

id contains the order ID as an integer.

orderinfo contains basic order details. The following array is returned:

  • source_url: The url of the store
  • order_status: The name of the order status, e.g. Payment received
  • credit_status: Either CREDIT or PAID
  • order_datetime: Format YYY-MM-DD HH:MN:SS e.g. 2024-12-15 16:05:22
  • order_customer_id: integer of the store customer ID
  • order_ponumber: PO number as a string
  • LineAmountTypes: Either Exclusive or Inclusive. States whether tax is included in the lineitem amounts.

billto contains billing information. The following array is returned:

  • name: string
  • company: string
  • address: string
  • address_line2: string
  • city: string
  • postcode: string
  • region: string
  • country: string
  • phone: string
  • email: string

shipto contains shipping address. The following array is returned:

  • name: string
  • company: string
  • address: string
  • address_line2: string
  • city: string
  • postcode: string
  • region: string
  • country: string

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:

  • description: product name, shipping charge title, discount title etc.
  • sku: SKU of product lines, empty fo non-product lines
  • quantity: integer
  • unitamount: numeric value of each unit (1 quantity), 4 decimals
  • accountcode: as defined in the API configuration
  • taxtype: as defined in the API configuration
  • taxamount: numeric value of the tax amount of each unit (1 quantity), 4 decimals

 

Example structure of 2 orders, each with 2 lineitems:

 

{
  "timestamp": "20241214221500",
  "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:

 

{
  "timestamp": "20241214221500",
  "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": ""
        }
      ]
    }
  ]
}