General principies of integration

  • All Retail Rocket API are available over HTTP/2 protocol;
  • If a method call requires the transfer of data in the request body, then the system expects it in JSON format and corresponding HTTP header: content-type: application/json;
  • All data that is returned as a result of the call is in JSON format;
  • The HTTP responses are important. Possible statuses of methods are described in its documentation;
  • In order to optimize connection speed and transfering of data, the connection should be cached;
  • You do not need to wait for a response when you send events, the only exception is batch loading of events, the details of which are described in the corresponding section;
  • Important: While using API methods in real applications/systems, be sure to take into account the possibility of API failure. It is necessary to request data asynchronously, with a maximum timeout of 500ms. It is mandatory to provide a fallback scenario in which the application/system must continue to work normally even if the API method did not respond or responded with an error;

Online store identificator

The API uses the partnerId parameter to identify the online store. The parameter's value is generated after registration in the Retail Rocket system, and can be obtained by a request to account manager, or in the Retail Rocket personal account.

πŸ“˜

The value is public and can be used open

Authorization

Some API methods have limited access and require an apiKey parameter, the value of which can be obtained from a Retail Rocket account manager.

❗️

The value of apiKey is secret and should not be passed or stored on the client side. (Website or mobile app)

🚧

In case of leaking the value of apiKey you should request a new one from the Retail Rocket account manager. The old value will no longer be valid.

πŸ“˜

Recommendation

Store the value of apiKey parameter in a store where it can be changed without having to release a new version of the website / mobile application.

Method's call timestamp

For the correct work of many Retail Rocket products, you need to know a time when a method was called; for this some API methods provide an optional parameter timestamp, in the value of which the Retail Rocket system expects a date and time in ISO 8601 format.

If the optional parameter is not specified, the Retail Rocket server time will be used as the value of timestamp.

Product information

If the API method requires products information (for example product / stockID, etc.), the value of such parameters must match the values passed to Retail Rocket product base in the XML-file or Product API.

Response Statuses

Response codeNameDescription
200ОКRequest accepted
204NoContentNo results found for request
400BadRequestThere is an error in the request, it is necessary to check the correctness of request forming
401UnauthorizedAuthentication error, it is necessary to check the correctness of the partnerId and ApiKey
403ForbiddenAccess is denied
404NotFoundThe requested resource was not found, it is necessary to check the correctness of URL
429TooManyRequestsRequest limit exceeded

Response time

Request processing time in Retail Rocket platform is up to 100 ms. Response time may be different due to specific of network infrastructure.

πŸ“˜

By default the site is limited to 600 requests per second. If necessary, it is possible to increase the limit. (with the help of an account manager)