# Products Catalog API Endpoints

# Preface

Quicklizard's Catalog API endpoints provide access to products with price recommendations that are currently, based on your pricing rules, and the list of products you added to our system, either via our SDK, API or other means.

Kindly note, that Quicklizard's product catalog may not contains your entire product set (depending on how our system was set up for you specifically). Additionally, products that were not actively updated either via our API, or by our pricing engine, will be removed from our system automatically after 60 days of inactivity. You may use the ttl field in the API response to determine when each product is scheduled for removal, and act accordingly.

Finally, products that are marked as disabled will not appear in API responses, and will not be available to our pricing engine until they are enabled again. Please refer to the Bulk Operations documentation for more information on enabling and disabling products.

# /api/v2/products

Endpoint - GET /api/v2/products

List products with price recommendations, sorted by descending price recommendation date, with pagination. Includes price recommendations generated by Quicklizard on your products over a given time period.

Please note - Only enabled products will be returned by this API endpoint. Products which were marked as disabled will be excluded, until you enable them again.

# Request parameters

page [Integer] - results page number
per_page [Integer] - results per page (defaults to 30, with maximum of 500 results per page)
period [String/Object] - pricing date period, as either time-worded string or as a Unix timestamp date range.
- Time-worded string values are formatted as N.period where N is a positive number and period is one of hours/days/weeks. For example, 1.days will fetch products priced between now and 1 day ago.
- Date range takes a to and from fields containing the pricing date start and end period as date-formatted strings in the format YYYYMMDDHH
priced_competitors [String] - optional flag to fetch products without competitor prices. Accepts only a single value: none. Use by passing priced_competitors=none in request query-string

# Example Request - Fetch the first 50 products

curl -XGET -H 'API_KEY: YOUR_API_KEY_HERE' -H 'API_DIGEST: YOUR_API_DIGEST_HERE' \
'https://api.quicklizard.com/api/v2/products?page=1&per_page=50'

# Example Request - Fetch the first 50 products priced in the past 24 hours

curl -XGET -H 'API_KEY: YOUR_API_KEY_HERE' -H 'API_DIGEST: YOUR_API_DIGEST_HERE' \
'https://api.quicklizard.com/api/v2/products?page=1&per_page=50&period=24.hours'

# Example Request - Fetch the first 50 products priced in a date range

curl -XGET -H 'API_KEY: YOUR_API_KEY_HERE' -H 'API_DIGEST: YOUR_API_DIGEST_HERE' \
'https://api.quicklizard.com/api/v2/products?page=1&per_page=50&period[from]=2015020100&period[to]=2015020123

# Example Request - Fetch the first 50 products without competitor prices

curl -XGET -H 'API_KEY: YOUR_API_KEY_HERE' -H 'API_DIGEST: YOUR_API_DIGEST_HERE' \
'https://api.quicklizard.com/api/v2/products?page=1&per_page=50&priced_competitors=none'

# /api/v2/products/:uid

Endpoint - GET /api/v2/products/:uid

Get product with price recommendation by QL UID

# Request parameters

uid [String] - product QL UID

# /api/v2/products/confirmed

Endpoint - GET /api/v2/products/confirmed

List products with confirmed or manually edited price recommendations, sorted by descending price recommendation date, with pagination.

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/v2/products/confirmed 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.

# Request parameters

page [Integer] - results page number
per_page [Integer] - results per page (defaults to 30, with maximum of 500 results per page)
period [String] - price recommendation acceptance period, as time-worded string. Time-worded string values are formatted as N.period where N is a positive number and period is one of hours/days/weeks. For example, 1.days will fetch recommendations that were accepted between now and 1 day ago.

Important!

The period parameter refers to the time the price recommendation was accepted, and not when the product was last priced.

# Example Request - Fetch the first 50 products, accepted or editing in the past 2 hours

curl -XGET -H 'API_KEY: YOUR_API_KEY_HERE' -H 'API_DIGEST: YOUR_API_DIGEST_HERE' \
'https://api.quicklizard.com/api/v2/products/confirmed?page=1&per_page=50&period=2.hours'

# /api/v2/products/disabled

Endpoint - GET /api/v2/products/disabled

List disabled products, sorted by descending price recommendation date, with pagination.

# Request parameters

page [Integer] - results page number
per_page [Integer] - results per page (defaults to 30, with maximum of 500 results per page)

# Example Request - Fetch the first 50 disabled products

curl -XGET -H 'API_KEY: YOUR_API_KEY_HERE' -H 'API_DIGEST: YOUR_API_DIGEST_HERE' \
'https://api.quicklizard.com/api/v2/products/disabled?page=1&per_page=50'

# /api/v2/products/enabled

Endpoint - GET /api/v2/products/enabled

List enabled products, sorted by descending price recommendation date, with pagination.

# Request parameters

page [Integer] - results page number
per_page [Integer] - results per page (defaults to 30, with maximum of 500 results per page)

# Example Request - Fetch the first 50 enabled products

curl -XGET -H 'API_KEY: YOUR_API_KEY_HERE' -H 'API_DIGEST: YOUR_API_DIGEST_HERE' \
'https://api.quicklizard.com/api/v2/products/enabled?page=1&per_page=50'

# API Response Format

{
  "total":1000
  "result": [
    {
      "client_key":"YOUR_CLIENT_KEY",
      "uid":"qwertgfdcvbnmjuik",
      "label":"Apple iPhone 6 16GB White",
      "prices": [
        {
          "shelf":150.0,
          "auto":150.0,
          "final":150.0,
          "delta":{
            "amount":0.0,
            "percent":0.0
          },
          "tag": "default",
          "group_name": "general",
          "group_id": 726,
          "desc": "No pricing change required",
          "updated_at":"2015-02-18T13:24:51Z",
          "confirmed": 0
        }
      ],
      "meta": {
        "permalink": "http://yourstore.com/products/your-product.html"
      },
      "attrs":[
        {
          "uid":"abvcderftygfdr45",
          "name":"brand",
          "value":"Apple"
        }
      ],
      "activity":{
        "24hr":{
          "views":4.0,
          "conversions":2.0,
          "revenue":0.0,
          "conversion_rate":0.0,
          "new_users": 1
        }
      },
      "marketplace":[
        {
          "product":"Apple iPhone 6 White 16GB",
          "price":{
            "current":151.0,
            "prev":155.0,
            "delta":4.0
          },
          "competitor":"competitor_a",
          "updated_at":"2015-02-18T13:24:51Z"
        }
      ],
      "ttl": "2015-04-12T11:20:57Z"
    }
  ]
}

# Response Fields

total [Integer] - total number of products found in catalog based on API call query
results [Array] - list of products where each product has the following fields:

client_key [String] - your Quicklizard client key
uid [String] - product unique identifier on the Quicklizard platform
label [String] - product label / title / name
prices [Array] - product prices array
- shelf [Float] - product shelf price
- auto [Float] - product interim recommended price, without pricing limits
- final [Float] - product final recommended price, with pricing limits
- delta [Object] - difference between shelf and recommended prices in percent and amount
- updated_at [String] - price update time (UTC) as ISO formatted string
- group_name [String] - the pricing group name the product belongs to
- group_id [Int] - the pricing group internal ID the product belongs to
- desc [String] - price recommendation reason
- tag [String] - price channel (relevant if your account supports multiple price channels)
- confirmed [Integer] - confirmed price flag - 1 for confirmed, 0 for not confirmed
meta [Object] - product meta data object
- permalink [String] - product permalink on your online store
- original_uid [String] - product original uid sent from SDK
attrs [Array] - product attributes list
- uid [String] - attribute internal unique identifier
- name [String] - attribute name
- value [String] - attribute value
activity [Object] - product activity object, containing past 24h activity (excluded from /api/v2/products/confirmed)
- views [Float] - total product views
- conversions [Float] - total product conversions (sales)
- conversion_rate [Float] - product conversion rate
- revenue [Float] - total product revenue
- new_users [Float] - total number of conversions (sales) made by new users
marketplace [Array] - list of competitor products and prices
- product [String] - competitor product name
- competitor [String] - competitor name
- price [Object] - competitor product price object
  - current [Float] - current competitor price
  - prev [Float] - previous competitor price
  - delta [Float] - difference between current and previous competitor prices
- updated_at [String] - competitor price update time as ISO formatted string
ttl [String] - product expiry date (UTC) as ISO formatted string