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 asamount, ornullwhen there is none. A deal hastext,type,min_qty,unit_priceandcondition. 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 ownidand a new fieldreplaced_fromset to the old id (nullon every other product).PUT /v1/sku-mappings/{sku}with the old id links the SKU to the website product. Store the newidwhen you seereplaced_from. No change is needed if you ignore fields you don't recognise. - Catalogue products are marked. Products and a comparison set's
own_producthave a new field,is_catalogue:truefor a product built from a catalogue you upload,falsefor every product from your online shop. Such a product has no page on your shop, so itsurlis 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}andPUT /v1/sku-mappingsanswer404for it, and its SKU answersno_comparison_setwithproduct_id: null. The SKU's link to it is hidden too:GET /v1/sku-mappingsleaves it out,GETandDELETE /v1/sku-mappings/{sku}answer404, and aPUT /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 answers409with the new codesku_on_website, andproduct_idin the body names the website product; nothing changes. This is checked beforeIf-None-MatchandIf-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-Matchon a hidden link stays412. A hidden link is oneGET /v1/sku-mappings/{sku}answers404for, such as a link to a product that left your catalogue. Before, a create-onlyPUTover it answered412.
#
- 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
typeURL now redirects to its row on the Errors page.
Documentation
- Documented what each
401says:unauthenticatedfor a missing header,invalid_keywith adetailof "The API key is malformed." or "The API key is not valid." - Documented that surrounding whitespace in
skuis trimmed and an internal control character is400 invalid_parameter; which body checks run before the scope check; and that an emptycursor=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.