--- title: "Retail Express API" description: "Getting Started with the Retail Express API" url: "https://developer.retailexpress.com.au/retail-express-api" image: "https://developer.retailexpress.com.au/_og/d/c_Ocean.takumi,title_Retail+Express+API,description_Getting+Started+with+the+Retail+Express+API,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMyMTk2RjMifX19,p_Ii9yZXRhaWwtZXhwcmVzcy1hcGki,s_JnrJa2vTJTbe46CV.png" --- ## [Getting Started with the Retail Express API](#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 APIs 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. --- ### [Notice – Upcoming API Endpoint Changes](#notice-upcoming-api-endpoint-changes) **Any example requests or sample endpoints in this documentation that reference URLs other than [https://api.retailexpress.com.au/](https://api.retailexpress.com.au/)\* will soon be retired. It is strongly recommended that you review any existing and future integrations to ensure only this primary base URL is used for all REST API calls to avoid disruption.** - These changes will take effect in _**September 2026**_. - All alternative URLs will stop working after the cutover. - After the cutover, examples in this documentation will be updated to reflect only the supported base URL. - SOAP APIs remain unchanged, and current documentation is accurate. --- ## [Versions](#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 - 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](#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](#making-requests-to-an-api-version) The API version is included in the URL used when making requests: /{version}/{endpoint} For example, the following URL makes a request to V2.1 (the latest version) of the API: /v2.1/products --- ## [Request/Response Format](#requestresponse-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}}](https://api.retailexpress.com.au/%7B%7Bversion%7D%7D/%7B%7Bendpoint%7D%7D) For example: [https://api.retailexpress.com.au/v2.1/customers](https://api.retailexpress.com.au/v2.1/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.1/customers/300001](https://api.retailexpress.com.au/v2.1/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](#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.1/products?sku=PRODSKU001](https://api.retailexpress.com.au/v2.1/products?sku=PRODSKU001) --- ## [Authorisation](#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.1/auth/token](https://api.retailexpress.com.au/v2.1/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](#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](#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](#datetime-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](#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 Specifications](https://developer.retailexpress.com.au/apis/5aee6e1e-b985-4e6f-b1f6-acc7e3d75abc)