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. At launch v2 is the latest supported version of the API. Any breaking changes in the API will be released as a new version however non-breaking changes will continue to be released in the current version.

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.

A limited number of active versions will be supported and non-supported versions will be retired from the product. While the exact timeframes for API version support are still being determined, any active version of the API will be supported for a minimum of 12 months following release.

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/customers
https://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-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
x-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