Skip to content

Policies

Changelog

Dated changes to the GetPrice API v1, newest first. Within v1 we only add things; see Versioning for what counts as breaking and how retirements are announced.

Unreleased#

  • Prices carry multi-buy deals. Every price object has a new field, deal: the multi-buy or member deal the retailer shows next to that price (such as "BUY 2 OR MORE For R 95.00"), read from the same price reading as amount, or null when there is none. A deal has text, type, min_qty, unit_price and condition. It is never the price: amount, "cheapest" and "position" are unchanged. See Multi-buy deals. No change is needed if you ignore fields you don't recognise.
  • A catalogue product taken over by your website keeps its id working. When the same product appears on your website, the website product takes over its SKU and comparison set. GET /v1/products/{id} with the old id then returns the website product, with its own id and a new field replaced_from set to the old id (null on every other product). PUT /v1/sku-mappings/{sku} with the old id links the SKU to the website product. Store the new id when you see replaced_from. No change is needed if you ignore fields you don't recognise.
  • Catalogue products are marked. Products and a comparison set's own_product have a new field, is_catalogue: true for a product built from a catalogue you upload, false for every product from your online shop. Such a product has no page on your shop, so its url is a fixed GetPrice page, Catalogue products. No change is needed if you ignore fields you don't recognise.
  • Products built from a catalogue you upload appear in the API once their comparison set exists. Until then such a product is not listed by GET /v1/products, GET /v1/products/{id} and PUT /v1/sku-mappings answer 404 for it, and its SKU answers no_comparison_set with product_id: null. The SKU's link to it is hidden too: GET /v1/sku-mappings leaves it out, GET and DELETE /v1/sku-mappings/{sku} answer 404, and a PUT /v1/sku-mappings/{sku} replaces it with your own link (your mapping always wins). Products from your website are unchanged.
  • A SKU on one of your website products stays with it. PUT /v1/sku-mappings/{sku} that would link such a SKU to a product built from your catalogue answers 409 with the new code sku_on_website, and product_id in the body names the website product; nothing changes. This is checked before If-None-Match and If-Match. Links between website products, and from a catalogue product to a website product, are unchanged. 409 conflict (listed before as reserved) can now answer a SKU mapping write that clashes with another change.
  • If-None-Match: * treats a hidden link as absent and replaces it (201); If-Match on a hidden link stays 412. A hidden link is one GET /v1/sku-mappings/{sku} answers 404 for, such as a link to a product that left your catalogue. Before, a create-only PUT over it answered 412.

#

  • v1 released: comparison sets, products, competitors, SKU mappings and the key check, as listed in the API reference.
  • API keys are self-serve: an admin creates, regenerates or revokes your organisation's key in Settings → API & Integrations. See Authentication.
  • Every error type URL now redirects to its row on the Errors page.

Documentation

  • Documented what each 401 says: unauthenticated for a missing header, invalid_key with a detail of "The API key is malformed." or "The API key is not valid."
  • Documented that surrounding whitespace in sku is trimmed and an internal control character is 400 invalid_parameter; which body checks run before the scope check; and that an empty cursor= returns the first page.
  • Examples use a neutral catalogue (a TV, a drill, a kettle, an air conditioner and rooibos tea) and four fictional retailers on example.com. Code samples: cURL, Python, TypeScript, PHP and C#. ERP recipes live under ERP integrations.