Skip to content

Concepts

Core concepts

Products: yours and your competitors'#

GetPrice collects products from your own online shop and from your competitors' websites. Every product has an id starting prd_. GET /v1/products lists only your own products, each with its SKUs and its comparison_set_id. Competitor products appear inside comparison sets.

Comparison sets#

A comparison set (set_…) is one of your products plus the same item at each competitor. For example: a 55-inch 4K UHD Smart TV in your shop, and the same model at Kestrel Electronics, Marula Online and Summit Cash & Carry. Your team builds the sets in the GetPrice dashboard, and the API returns them as the dashboard shows them.

  • Each item in competitors is a competitor listing: one competitor's product page for the same item.
  • A set normally holds one listing per competitor, and its integrity is ok.
  • "integrity": "retailer_conflict" means the set holds more than one listing from one retailer, such as two pack sizes. You get all of them. Take the lowest price per retailer, or flag the set for a buyer to review.
  • own_product is null when the set tracks an item you don't sell online.

SKU mappings#

A SKU is your own product code: the stock code, item code or ERP reference your systems already use. A SKU mapping links one of your SKUs to one of your products in GetPrice. With that link in place, GET /v1/comparison-sets?sku=TV-55UHD finds the right set.

  • SKUs match regardless of upper or lower case. Whitespace at either end is trimmed: spaces, tabs, line breaks and non-breaking spaces.
  • Every other character counts, including leading zeros: 00981A and 981A are different SKUs.
  • Unicode isn't normalised, so send codes exactly as your ERP stores them: é typed as one character and e plus a combining accent are different SKUs, and ß doesn't match SS.
  • One SKU points at one product. One product can have several SKUs.
  • A SKU is at most 100 characters and can't contain line breaks or other control characters. Trimming applies only to the ends: a tab or other control character inside the value is 400 invalid_parameter.
  • A SKU that is exactly . or .. can't be sent in a URL path: HTTP clients remove such path segments.
  • GET /v1/sku-mappings lists every link. Each link's source says where it came from:
sourceThe link was
site_skuread from the code on your own website, so it worked from day one
apicreated through this API
list_skumade in the GetPrice dashboard, on a comparison set
import, settings_uploadloaded from a file by GetPrice

A link normally points at a product (product_id). For a set with no product of yours, GetPrice may link the SKU to the set itself (comparison_set_id). A PUT replaces that with a link to a product.

Your codes#

The SKUs on your own online shop are pre-loaded as SKU mappings. Every SKU your shop shows works from day one. SKUs your shop doesn't show, such as pack, case or internal codes, need linking first.

When you look up SKUs, skus gives each SKU you sent a status:

StatusMeaningWhat to do
foundLinked to your product, which has a comparison setRead the set in data
no_comparison_setLinked to your product, but no comparison set exists yetAsk your GetPrice contact if you need one
unknown_skuNot linked to any of your productsCheck the SKU, or link it

Your system may code one item several ways. Take a box of rooibos tea:

CodeWhat it isOn your online shop?
TEA-RB80Base codeNo
TEA-RB80-EAOne box of 80 tea bagsYes, so GetPrice collects and compares it
TEA-RB80-C12Case of 12 boxesNo

TEA-RB80-EA works straight away. TEA-RB80-C12 answers unknown_sku until you link it to the TEA-RB80-EA product with PUT /v1/sku-mappings/TEA-RB80-C12. Even then, you get single-box prices.

Note: GetPrice never multiplies unit prices into pack prices. No retailer prices a case at exactly 12 times the unit price. If you link pack codes, convert in your own system, where you know the pack size.

Catalogue products#

Some of your products may not be on your online shop, such as items you sell only to trade customers. GetPrice can build them from a catalogue you upload. The dashboard marks them "From your catalogue".

  • is_catalogue is true for such a product, in GET /v1/products, GET /v1/products/{id} and a comparison set's own_product. It is false for every product from your online shop.
  • A catalogue product has no page on your shop, so its url is a fixed GetPrice page: https://www.getprice.ai/developers/core-concepts#catalogue-products, this section. Don't show it to buyers as a product page.
  • A catalogue product appears in the API once its comparison set exists. Until then it isn't listed, GET /v1/products/{id} returns 404, and its SKU answers no_comparison_set with product_id: null.
  • Competitor listings are never catalogue products: their url is always the competitor's page.
  • When the same product later appears on your online shop, the website product takes over: your SKU and the comparison set move to it, and the catalogue product is retired. See Ids are opaque for what happens to the old id.

Prices and last_collected_at#

Every price is an object:

JSON
{
  "amount": "8499.00",
  "was": "9499.00",
  "currency": "ZAR",
  "deal": null
}
FieldMeaning
amountThe price a shopper pays now, as a string with two decimals
wasThe original price during a promotion, otherwise null
currencyThe ISO 4217 code, always present
dealA multi-buy or member deal shown next to the price, otherwise null. See Multi-buy deals

Convert amount with a decimal type, such as Python's Decimal. A float can turn 18.99 into 18.989999….

Next to every price sits last_collected_at: the last time GetPrice successfully read that price. It moves forward on every collection, even when the price stays the same. Use it as your freshness date.

It doesn't mean "when the price last changed". A failed or rejected reading doesn't move it, so you keep the last good price and its time. price and last_collected_at are both null when GetPrice has no valid price yet.

Prices, discounts and promotions#

Every price shows what a shopper pays now and, during a promotion, what they would have paid.

FieldOn promotionNot on promotion
amountThe discounted price a shopper pays nowThe normal price
wasThe original price the retailer showsnull
  • GetPrice sends was only when it's strictly greater than amount. Otherwise was is null. The saving is was minus amount.
  • was comes from the same price reading as amount, so both are as fresh as last_collected_at.
  • "Cheapest" and "position" in GetPrice always use amount, the price a shopper pays.

For example, {"amount": "8499.00", "was": "9499.00"} reads as R8499.00, was R9499.00, which is about 10.5% off.

Multi-buy deals#

Some retailers show a deal next to the price, such as "BUY 2 OR MORE For R 95.00". GetPrice sends it in price.deal, read from the same price reading as amount. When that reading shows no deal, deal is null.

JSON
{
  "amount": "100.00",
  "was": null,
  "currency": "ZAR",
  "deal": {
    "text": "BUY 2 OR MORE For R 95.00",
    "type": "tiered_unit",
    "min_qty": 2,
    "unit_price": "95.00",
    "condition": "none"
  }
}
FieldMeaning
textThe deal exactly as the retailer's website shows it, always present
typeHow GetPrice reads the deal (below), or null if it isn't classified
min_qtyHow many items to buy to get the deal, or null
unit_priceThe price of one item when you buy min_qty under the deal, in the price's currency, or null
conditionWho gets it: none (every shopper), loyalty (loyalty members only) or online_only, or null

type is one of:

typeExampleunit_price
tiered_unit"BUY 2 OR MORE For R 95.00"95.00
multi_buy_total"2 for R30"15.00
buy_x_pay_y"Buy 3, pay for 2"Two-thirds of the price
buy_x_save_pct"Buy 2, save 10%"The price less 10%
buy_x_save_amount"Buy 2, save R10"The price less R5
member_priceA loyalty or member priceThe member price
unparsedText GetPrice keeps but can't turn into a price per itemnull
  • A deal is never the price. amount stays the price of one item, and "cheapest" and "position" in GetPrice never use the deal. Compare deal.unit_price with amount yourself if you want the multi-buy view.
  • unparsed means GetPrice kept the retailer's text but couldn't read a reliable price per item from it, so min_qty and unit_price are null. Often the "deal" is no cheaper than the shelf price. Show the text if you show anything.
  • A loyalty or online_only deal isn't available to every shopper in store.
  • type and condition are open sets: treat a value you don't recognise like unparsed, or show only the text.

stale#

stale: true means a product hasn't been collected for longer than expected, or has no price at all. "Longer than expected" means your collection schedule's longest gap plus 24 hours. On a Monday, Wednesday and Friday schedule, that's 96 hours.

You still get the price, but the retailer may have changed it since. A stale flag usually means the competitor's site changed or blocked collection. GetPrice monitors this, and you're welcome to ask us about it.

status and availability#

  • status is active while a product is listed on the competitor's site. Products that disappeared are delisted, and you only get them with include_delisted=true.
  • availability describes stock. GetPrice doesn't collect stock levels yet, so it's unknown for now. Expect values such as in_stock and out_of_stock later.

match: is it the same item?#

Every competitor listing says how it got into the set:

FieldValueMeaning
reviewsameConfirmed as the same item
with_differences
unreviewedIn the set, but not confirmed yet
reviewed_bycustomerConfirmed by one of your own users
getpriceConfirmed by GetPrice's matching team
nullNot confirmed by anyone yet
confidence0–1 or nullGetPrice's match confidence, where a machine match backs it

Add reviewed_by=customer to any comparison-set call to get only matches your buyers confirmed. If you set prices automatically, use same listings only. The dashboard also leaves unreviewed listings out of "cheapest".

Ids are opaque#

Ids such as prd_8fK2mQa1, set_x7Kp2Lm9 and cmp_3LqV8nP2 are case-sensitive strings of up to 32 characters. Store them as text and compare them exactly. Don't parse them.

An id that belongs to another company behaves like one that doesn't exist: you get 404. When two sets are merged, the old id returns the surviving set, with a different id. Key your integration on linked SKUs and this never matters: your pre-loaded shop codes, and any SKU you link with PUT /v1/sku-mappings/{sku}.

The same holds when a catalogue product is taken over by the same product on your website. GET /v1/products/{id} with the old id returns the website product, with its own id and replaced_from set to the old id; it is not a redirect. PUT /v1/sku-mappings/{sku} with the old id links the SKU to the website product. Your linked SKU already points at the website product, so a SKU lookup needs no change. Replace the old id with the new one when you see replaced_from. The old id is never listed by GET /v1/products.