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: Baked Beans 410g in your shop, and the same tin at Harbour Market, Cape Fresh and Northwind Wholesale. Your team builds the sets in the GetPrice dashboard, and the API returns them as the dashboard shows them.

• 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#

Your ERP knows products by your own codes. 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=10072L 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.
• 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.

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 stock codes on your own online shop are pre-loaded as SKU links. Every code your shop shows works from day one. Codes your shop doesn't show, such as pack, case or internal codes, need linking first.

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

Your system may code one item several ways. Take a 100ml tube of toothpaste:

11247L works straight away. 11247P answers unknown_sku until you link it to the 11247L product with PUT /v1/sku-mappings/11247P. Even then, you get single-unit prices.

Prices and last_collected_at#

Every price is an object:

{
  "amount": "17.99",
  "was": "19.99",
  "currency": "ZAR"
}

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.

• 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": "17.99", "was": "19.99"} reads as R17.99 (was R19.99 — 10% off).

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 entry says how it got into the set:

Add reviewed_by=customer to any comparison-set call to get only matches your buyers confirmed. If you set prices automatically, use same entries only. The dashboard also leaves unreviewed entries 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}.