Getting Started with the Retail Express API

The Retail Express API allows developers to integrate with and extend the in-built features of the Retail Express platform. It is a RESTful API based on the OpenAPI specification and is the focus for all development and enhancement moving forwards.

This Retail Express API is a modern, secure, and standards based API designed to eventually replace all of our legacy SOAP XML services:

  • Webstore/eCommerce

  • Warehouse Management

  • Inventory Planning

  • Accounting

Our existing legacy API’s will continue to operate uninterrupted. We encourage our partners and customers to utilise both the existing legacy web services and the Retail Express API to achieve your desired integration outcomes. Over time, the new API will be extended and updated to eventually replace all functions included in the legacy API’s. When that occurs, we will provide at least 2 years notice for the retirement of the legacy API’s.

Versions

The Retail Express API is versioned allowing changes to be rolled out without impacting existing integrations and functionality. When breaking changes are made to the API, a new version of the API will be released at which point it becomes the Latest version of the API.

Breaking changes include:

  • a change in the format of the response data for one or more calls;

  • a change in the response type (i.e. changing an integer to a float);

  • removing any part of the API.

Non-breaking changes include:

  • adding new endpoints;

  • adding new optional request parameters;

  • adding new response properties.

The previous version of the API will continue to work and will be supported for use in integrations for a minimum of 12 months from the release of the Latest version.

Latest Version vs Supported Version

The Latest version of the API will receive all future updates and improvements including new fields and new endpoints. The previous Supported version will NOT receive these new additions but will continue to be supported and will receive bug fixes where required.

We recommend that existing integrations be upgraded to the Latest version of the API as soon as possible. We will provide advance notice of a previous Supported version of the API no longer being available.

Current Versions

There are currently two versions of the Retail Express API available:

Supported
Retail Express API V2 (released February 2021, Supported until April 2024)

Latest
Retail Express API V2.1 (released April 2023)

Breaking changes in V2.1

GET Customers / GET Customers/{id}

  • company, mobile, phone, and email removed from billing_address object in response

GET Orders / GET Orders/{id}

  • last_name renamed to surname in customer object in response

GET Outlets / GET Outlets/{id}

  • code renamed to currency_code in fob_currency object in response

  • name renamed to currency_name in fob_currency object in response

  • outlet_id renamed to id in default_source_outlet object in response

  • outlet_name renamed to name in default_source_outlet object in response

  • outlet_id renamed to id in default_fulfil_outlet object in response

  • outlet_name renamed to name in default_fulfil_outlet object in response

GET Products / GET Product/{id}

  • carton_quantity field type changed from integer to string in response

As of the 3rd of April, 2023 V2.1 is the Latest version of the API and is the recommended version to use for all new integrations. The previous version - V2 - will continue to function and be supported for a minimum of 12 months i.e. until April 2024.

Making Requests to an API Version

The API version is included in the URL used when making requests:

/{version}/{endpoint}.json

For example, the following URL makes a request to V2.1 (the latest version) of the API:

/v2.1/products.json

Request/Response Format

The Retail Express API supports JSON-encoded responses for requests and responses. Headers for all requests should set both Accept and Content-Type to application/json.

All requests are made to a standard URL path as follows:

https://api.retailexpress.com.au/{{version}}/{{endpoint}}

For example:

https://api.retailexpress.com.au/v2/customers

HTTP GET

Most resources allow you to retrieve either a full, paginated list of items or a specific item through passing an identifier at the end of the endpoint path:

https://api.retailexpress.com.au/v2/customershttps://api.retailexpress.com.au/v2/customers/300001

HTTP POST / PUT

In the Retail Express API, a POST request will create a new resource whereas a PUT will update an existing resource and requires an identifier to be passed in the path. Not all resources currently support POST/PUT requests but support for these functions will be improved over time.

HTTP DELETE

A DELETE request will delete or disable a resource and requires an identifier be passed in the path. Note that in most situations, a DELETE will perform a “soft delete” or disable of the item rather than deleting the resource from the system. There is currently limited support for DELETE operations in the API.

Filtering and Searching

Most resources allow for the passing of one or more query parameters to filter the results of a GET request. Some parameters only allow single options to be passed, whereas others support comma separated lists that will match any of the supplied options.

An example of a query filter would be:

https://api.retailexpress.com.au/v2/products?sku=PRODSKU001

Authorisation

All developers will require an API Key which can be used to generate an access token that is used to authenticate all subsequent requests. Before making calls to a Retail Express client, you must first request an API Key from the client you wish to integrate with. Each API Key is unique to a given client and only provides access to that clients’ data.

Each access token will expire after 60 minutes at which point a new token must be requested.

To authenticate with the Retail Express API, first make a call to the Authentication Token endpoint, passing your API Key in header parameter x-api-key:

https://api.retailexpress.com.au/v2/auth/token

Assuming a valid API Key is passed, an access token will be returned along with the date/time when it will expire:

{

    "token_type": "Bearer",    "access_token": "eyJhbmdWxsX2FjY2VzcyJdfQ.IWPofNEfIu-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",    "expires_on": "2021-01-31T23:48:23.4672689+00:00"

} 

Requests to other endpoints in the API must include this token (in the Authorization header parameter) and the API Key (again in the x-api-key header parameter):

Authorization: Bearer eyJhbmdWxsX2FjY2VzcyJdfQ.IWPofNEfIu-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-api-key: hkldfhTYDnhlkadsfadsdfTYSDFNFDSF

Once a token expires, the same call to the Authentication Token endpoint is required to retrieve a new token. Once a token has expired, or if an invalid token is passed, a 401 Unauthorised response will be returned.

Rate Limits

The Retail Express API is rate limited to maintain the quality of service and performance of the platform. Currently rate limits are imposed on a client basis so if you integrate with multiple clients there will be a separate rate limit for each client / API Key. However, requests from all developers / API Keys count towards the rate limits so even if your application does not exceed the limits, you may still hit the limit for a given client.

There are two forms of limits imposed:

300 requests in any single 1 minute, or on average 5 requests per second

100,000 total requests in a 24 hour period

If you hit the per minute rate limit you will receive a 429 Too Many requests response and will need to retry your request after a short period of time.

If you hit the daily quota, you will again receive a 429 Too Many Requests response but you will not be able to make any further requests until the following day.

The per minute limits are designed to allow short bursts of frequent requests as required - integrations should not constantly make requests at these limits or the daily limit will be rapidly reached.

We expect all developers to design their integrations using industry standard techniques for limiting requests within these rate limits and to utilise caching techniques where possible to reduce the overall number of calls.

These rate limits may change at any time.

Pagination

GET requests to all endpoints will return a paginated response with a default of 20 items returned per page. The current page number, page size and total number of records returned are included in each response:

"page_number": 1,"page_size": 20,"total_records": 47

page_number and page_size can be passed as query parameters in the request to retrieve a specific set of records. The maximum page_size for all requests is 250.

Date/Time Formats

All date/times values in Retail Express are stored in Sydney (AEST/ADST) time and will be returned in the following format: “yyyy-mm-ddThh:mm:ss+TZD” e.g. “2020-09-24T23:15:46+10:00”.

When submitting requests that include dates and times you should include the time zone designator.

Response Codes

200 OK
The request was successfully processed

201 Created
The request was successfully processed and a new resource was created

400 Bad Request
The request was not understood, generally due to bad request syntax

401 Unauthorised
Invalid, missing, or expired credentials

404 Not Found
Requested resource or endpoint could not be found

429 Too Many Requests
The rate limits for the client have been exceeded

500 Internal Server Error
An internal error occurred in Retail Express. Please contact Support.

503 Service Unavailable
The server is currently unavailable. Please contact Support.

504 Gateway Timeout
The request timed out. Retail Express waits up to 60 seconds for a response.

View Specification