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
competitorsis a competitor listing: one competitor's product page for the same item. - A set normally holds one listing per competitor, and its
integrityisok. "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_productisnullwhen 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:
00981Aand981Aare different SKUs. - Unicode isn't normalised, so send codes exactly as your ERP stores them:
étyped as one character andeplus a combining accent are different SKUs, andßdoesn't matchSS. - 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-mappingslists every link. Each link'ssourcesays where it came from:
source | The link was |
|---|---|
site_sku | read from the code on your own website, so it worked from day one |
api | created through this API |
list_sku | made in the GetPrice dashboard, on a comparison set |
import, settings_upload | loaded 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:
| Status | Meaning | What to do |
|---|---|---|
found | Linked to your product, which has a comparison set | Read the set in data |
no_comparison_set | Linked to your product, but no comparison set exists yet | Ask your GetPrice contact if you need one |
unknown_sku | Not linked to any of your products | Check the SKU, or link it |
Your system may code one item several ways. Take a box of rooibos tea:
| Code | What it is | On your online shop? |
|---|---|---|
TEA-RB80 | Base code | No |
TEA-RB80-EA | One box of 80 tea bags | Yes, so GetPrice collects and compares it |
TEA-RB80-C12 | Case of 12 boxes | No |
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_catalogueistruefor such a product, inGET /v1/products,GET /v1/products/{id}and a comparison set'sown_product. It isfalsefor every product from your online shop.- A catalogue product has no page on your shop, so its
urlis 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}returns404, and its SKU answersno_comparison_setwithproduct_id: null. - Competitor listings are never catalogue products: their
urlis 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:
{
"amount": "8499.00",
"was": "9499.00",
"currency": "ZAR",
"deal": null
}| Field | Meaning |
|---|---|
amount | The price a shopper pays now, as a string with two decimals |
was | The original price during a promotion, otherwise null |
currency | The ISO 4217 code, always present |
deal | A 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.
| Field | On promotion | Not on promotion |
|---|---|---|
amount | The discounted price a shopper pays now | The normal price |
was | The original price the retailer shows | null |
- GetPrice sends
wasonly when it's strictly greater thanamount. Otherwisewasisnull. The saving iswasminusamount. wascomes from the same price reading asamount, so both are as fresh aslast_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.
{
"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"
}
}| Field | Meaning |
|---|---|
text | The deal exactly as the retailer's website shows it, always present |
type | How GetPrice reads the deal (below), or null if it isn't classified |
min_qty | How many items to buy to get the deal, or null |
unit_price | The price of one item when you buy min_qty under the deal, in the price's currency, or null |
condition | Who gets it: none (every shopper), loyalty (loyalty members only) or online_only, or null |
type is one of:
type | Example | unit_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_price | A loyalty or member price | The member price |
unparsed | Text GetPrice keeps but can't turn into a price per item | null |
- A deal is never the price.
amountstays the price of one item, and "cheapest" and "position" in GetPrice never use the deal. Comparedeal.unit_pricewithamountyourself if you want the multi-buy view. unparsedmeans GetPrice kept the retailer's text but couldn't read a reliable price per item from it, somin_qtyandunit_pricearenull. Often the "deal" is no cheaper than the shelf price. Show thetextif you show anything.- A
loyaltyoronline_onlydeal isn't available to every shopper in store. typeandconditionare open sets: treat a value you don't recognise likeunparsed, or show only thetext.
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#
statusisactivewhile a product is listed on the competitor's site. Products that disappeared aredelisted, and you only get them withinclude_delisted=true.availabilitydescribes stock. GetPrice doesn't collect stock levels yet, so it'sunknownfor now. Expect values such asin_stockandout_of_stocklater.
match: is it the same item?#
Every competitor listing says how it got into the set:
| Field | Value | Meaning |
|---|---|---|
review | same | Confirmed as the same item |
with_differences | ||
unreviewed | In the set, but not confirmed yet | |
reviewed_by | customer | Confirmed by one of your own users |
getprice | Confirmed by GetPrice's matching team | |
null | Not confirmed by anyone yet | |
confidence | 0–1 or null | GetPrice'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.