API Endpoints

Our REST API is documented with Swagger which is an industry-standard tool to describe API signatures. The API documentation is available here, and you should take a moment to read and and familiarize yourself with the available end-points, their request and response formats and payloads.

The purpose of this document is to provide a high-level overview of notable available API endpoints and their intended usage.

Please make sure you go over the complete API documentation available here.

Please Note

Due to a limitation in Swagger itself, numeric JSON fields that should contain numeric double values (or float64), are marked with a data-type of number($double), but are given an example value of 0 (zero) instead of 0.00 .

Please make sure you send numeric field values that are marked as number($double) in float64 / double format.

Price recommendations endpoints

Use these API endpoints to access available price recommendations generated by QL on your clients' sites products catalog.

GET /api/v3/recommendations/all

Access all price recommendations for a single site, identified by the client_key request parameter, in a given time period, with pagination.

Important

This endpoint is limited to returning up to 100K results for any given query.

Please see the integration documentation for more details on how to ingest larger quantities of data into your system.

API docs

GET /api/v3/recommendations/accepted

Access accepted and manually-edited price recommendations for a single site, identified by the client_key request parameter, in a given time period, with pagination.

Use this end-point to read recommendations that were accepted by one of your clients on QL's online platform, and save them into your ERP.

API sampling frequency

The confirmed recommendations API endpoint acts as a stream, and not a feed. Products can change their confirmed status during pricing if QL's price recommendation changed since the last recommendation was accepted.

We recommend that you call the /api/v3/recommendations/accepted endpoint every 15-30 minutes, with a period parameter of double that time (so period=30.minutes for a 15 minutes call frequency).

At the very least, we recommend that you call this API endpoint once an hour.

Important

This endpoint is limited to returning up to 100K results for any given query.

Please see the integration documentation for more details on how to ingest larger quantities of data into your system.

API docs

Products catalog endpoints

Multiple price channels support

In the bulk create / update API endpoints, you may pass one or more product price object. If your QL client account supports multiple price channels, you must tag each price channel accordingly. Otherwise, pass only a single price object, without tagging it.

POST /api/v3/products/create

Create new products for one or more of your client sites on QL's internal database. Newly created products will be processed by QL in due course and receive price recommendations based on rules defined by your client.

API docs

PUT /api/v3/products/update

Update existing products for one or more of your client sites on QL's internal database. Updates can include cost, inventory, new shelf prices or any additional product attributes.

Important

Please use this API endpoint to send updates on changed products only. Do not blindly send all your products for update, regardless of whether they contain changes or not, as this will cause unneeded load on our internal systems.

Updates should be sent based on the commercial agreement you have with QL. For example, if your agreement allows for one pricing per product per day, then sending inventory updates every hour will not result in additional pricing cycles, and is therefore redundant.

Deleting attributes

You can explicitly delete an attribute by passing delete! as its value. Attributes with a value of delete! that are sent to the /api/v3/products/update API will be deleted from their respective products.

API docs

GET /api/v3/products/disabled

Read all products for a single client site, identified by the client_key request parameter, that were disabled by you or your client. Disabled products are removed from QL's pricing flow, and are eventually deleted from our internal database after 60 days of inactivity.

API docs

GET /api/v3/products/enabled

Read all products for a single client site, identified by the client_key request parameter, that are enabled by you or your client. Enabled products will be priced by our pricing engine based on rules you or your client define in our online system.

API docs

POST /api/v3/products/upload

Create or update multiple products for a single client site by uploading a file containing JSON rows with information about new products or updates for existing products.

Use this endpoint to process a large number of products in batch.

Please Note

  • Uploaded file size is limited to 10MB - If your data exceeds 10MB, please split it into multiple files.
  • The name of the uploaded file is returned in the API response and can be used to check the processing status of your upload.
  • Please DO NOT use the uploaded file's content as part of your API signature

API docs

GET /api/v3/products/upload_status

Check the upload and processing status of files uploaded via POST /api/v3/products/upload

Please Note

The name of the uploaded file is returned in the POST /api/v3/products/upload API response.

API docs

Competitor prices endpoints

PUT /api/v3/competitors/prices

Update competitor prices for products belonging to one or more of your client sites on QL's internal database.

Use this endpoint to add or update competitor prices, available to you from a 3rd-party source, for products already available on QL's internal database.

Important

You should take care to send updates only on products that already exist on QL's internal database.

API docs

Product analytics endpoints

POST /api/v3/impressions

Update impression metrics (views, conversions, revenue) for products belonging to one or more of your sites on QL's internal database.

Use this endpoint to send QL aggregated impression metrics on products belonging to one or more of your sites, in case you cannot install our Javascript SDK, which collects this information in real-time.

Please Note

Impression metrics (views, conversions, revenue) will be distributed evenly across the provided date range on a per-hour basis.

For example, when you send an aggregated impression metrics item with 10 views, 5 conversions and $100 revenue, and a date range of 5 hours, it will be converted internally into 5 hourly impression items, with 2 views, 1 conversion and $20 revenue each.

API docs