# 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.
# 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.
# 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=yesto fetch only accepted and manually-edited recommendations. - changed - pass
changed=yesto 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.
# 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.
# 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.
# 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.
# 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.
# 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
# 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.
# 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.
# 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.