# 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 (opens new window), 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 (opens new window).

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 (opens new window)

# 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 (opens new window)

# GET /api/v3/recommendations/log

Access price recommendations for a single site, identified by the client_key request parameter, as a timestamp-sorted log, starting at a given timestamp.

This endpoint should be used to fetch recommendations as they become available, optionally filtered by:

  • accepted - pass accepted=yes to fetch only accepted and manually-edited recommendations.
  • changed - pass changed=yes to fetch only recommendations that are different than their product's shelf price.

This endpoint is not limited by result count, pagination or frequent price updates. Each recommended price is saved as a unique entry in the log. Data is available for 48hrs.

# Last ID

This endpoint returns a batch of recommendations, each identified by a unique ID (not to be confused with the product's UID). To support large number of results, we use that ID as a cursor, when fetching data from the endpoint. For each result set, you can use the last_id field of the response, to indicate that the next API call should fetch results starting with the ID following that last_id.

For example, if I have 1000 recommendations, and I fetched the first 200. To fetch the next 200, I take the ID of the last recommendation, and pass it as the value of the last_id parameter to the API. This will instruct the API to fetch the batch starting with the ID of item 201, and so on.

API sampling frequency

We recommend you make frequent calls to this endpoint, and fetch small batches of recommendations frequently, rather than large batches once or twice a day. At the very least, this endpoint should be called every 30 minutes.

API docs (opens new window)

# 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 (opens new window)

# 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 (opens new window)

# 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 (opens new window)

# 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 (opens new window)

# 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 (opens new window)

# 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 (opens new window)

# 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 (opens new window)

# 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 (opens new window)