Set up access
The Pricemind browser companion signs in with Pricemind and receives a credential with the scopes below. Your own client can call the same endpoints with an API key issued with these capabilities:
channels:readTracked shop domains.
products:readResolve a page, search your products, read a page check.
competitor_prices:readMatched offers (include=offers), offer history and the price history window.
rule_suggestions:readThe pricing rule outcome (include=rule and the rule-suggestion route).
product_pages:writeStart, confirm, retry and cancel a page check.
Existing keys do not gain new scopes. Create a replacement key with the capabilities you need, switch your client, then revoke the old key. The resolve and tracked-domains routes cover every channel of the key's account that the key may read; the other routes name one channel.
Look up only tracked shops
GET /v1/extension/tracked-domains lists, per channel, your own shop domain and the competitor shops the channel tracks. Use it to decide whether a page is worth looking up at all, so pages of other shops never leave the browser. Cache the list and revalidate it with If-None-Match; a 304 means nothing changed. Competitors are read live, including newly added ones.
[
{
"channel_id": 202,
"name": "Volta BG",
"currency": "EUR",
"own_domains": [
"own.example"
],
"competitors": [
{
"channel_competitor_id": 3101,
"domain": "market.example",
"status": "active"
},
{
"channel_competitor_id": 3102,
"domain": "shop.example",
"status": "active"
}
]
},
{
"channel_id": 203,
"name": "Volta RO",
"currency": "RON",
"own_domains": [
"own.ro"
],
"competitors": [
{
"channel_competitor_id": 3201,
"domain": "shop.example",
"status": "issues"
}
]
}
]Resolve a page
GET /v1/extension/resolve?url= returns every channel and product of the account the page belongs to, and viewed_as says what the page is. It matches the URL and its common variants (trailing slash, query, language prefix, www) and the shop's product-code fingerprint. url takes an http or https URL of at most 2,048 characters; a missing scheme means https.
curl 'https://api.pricemind.io/v1/extension/tracked-domains' \
--header "X-API-Key: $PRICEMIND_API_KEY"
curl --get 'https://api.pricemind.io/v1/extension/resolve' \
--header "X-API-Key: $PRICEMIND_API_KEY" \
--data-urlencode 'url=https://shop.example/product/0001' \
--data-urlencode 'include=offers,rule'
curl 'https://api.pricemind.io/v1/channels/202/products/12345/offers/67890/history?days=30' \
--header "X-API-Key: $PRICEMIND_API_KEY"
curl 'https://api.pricemind.io/v1/channels/202/products/12345/history?range=2w&basis=incl' \
--header "X-API-Key: $PRICEMIND_API_KEY"
curl 'https://api.pricemind.io/v1/channels/202/products/12345/rule-suggestion' \
--header "X-API-Key: $PRICEMIND_API_KEY"ownThe page is one of your channel products. competitor_product_domain_id is null.
competitorA matched competitor page, including marketplace pages and seller listings. The offer whose product.product_domain_id equals competitor_product_domain_id is the page itself.
unmatchedA known page of a shop you track that none of your products uses yet. page holds what Pricemind collected for it.
not_trackedAn unknown page, or a shop none of your channels tracks. Untracked shops are never looked up.
matches lists every channel match: two channels drive a channel selector, two products in one channel a product picker. Each main_product is the same Product as the catalog reads; with include=offers it carries its first 20 offers and an offer continuation in offers.links.next. include=rule adds each match's rule. trackable_channels lists channels where the page's shop is a competitor and the page is not matched yet, so it can be added to a product.
{
"domain": "shop.example",
"viewed_as": "competitor",
"matches": [
{
"channel_id": 202,
"main_product": {
"channel_id": 202,
"catalog": {
"product_domain_id": "12345",
"sku": "ABC/001",
"title": "Synthetic example kettle",
"url": "https://own.example/products/ABC-001",
"locale": "en-GB",
"description": {
"format": "html",
"content": "<p>Synthetic example description.</p>"
},
"brand": {
"id": "17",
"name": "Example Brand"
},
"codes": {
"ean": [
"0012345678905"
],
"sku": [
"ABC/001"
],
"mpn": [
"K-001"
]
},
"categories": [
{
"id": "12",
"name": "Kettles",
"path": [
"Kitchen",
"Appliances",
"Kettles"
]
}
],
"images": [
{
"url": "https://own.example/images/kettle-front.jpg",
"alt": "Front view",
"width": 1200,
"height": 1200
},
{
"url": "https://own.example/images/kettle-side.jpg",
"alt": null,
"width": null,
"height": null
}
],
"attributes": [
{
"name": "capacity",
"label": "Capacity",
"data_type": "decimal",
"value": "1.500",
"unit": "L"
},
{
"name": "features",
"label": null,
"data_type": "array",
"value": [
"quiet",
"automatic"
],
"unit": null
},
{
"name": "cordless",
"label": "Cordless",
"data_type": "boolean",
"value": true,
"unit": null
}
],
"variant": {
"is_configurable": false,
"parent_product_domain_id": null,
"attributes": [
{
"name": "colour",
"label": "Colour",
"data_type": "string",
"value": "Blue",
"unit": null
}
]
},
"custom_fields": [
{
"machine_name": "cost",
"label": "Cost",
"data_type": "decimal",
"value": "65.000"
}
],
"updated_at": "2026-09-14T08:00:00Z",
"field_status": {}
},
"price": {
"currency": "EUR",
"regular": {
"excl_tax": "100.00",
"incl_tax": "120.00"
},
"special": {
"excl_tax": "90.00",
"incl_tax": "108.00"
},
"effective": {
"excl_tax": "90.00",
"incl_tax": "108.00"
},
"delivery": {
"excl_tax": null,
"incl_tax": null
},
"tax_rate": "0.20",
"effective_includes_delivery": false,
"product_price_id": "998877",
"observed_at": "2026-09-14T08:00:00Z",
"stale_at": "2026-09-16T08:00:00Z"
},
"additional_prices": [],
"availability": 1,
"status": null,
"quality": {
"is_stale": false,
"eligible_for_comparison": true,
"reasons": []
},
"links": {
"self": "/v1/channels/202/products/12345",
"offers": "/v1/channels/202/products/12345/offers"
},
"offers": {
"data": [
"… OfferPage items, see the API reference …"
],
"pagination": {
"limit": 20,
"has_more": false,
"next_cursor": null
},
"links": {
"next": null
},
"meta": {
"consistency": "live",
"coverage": "selected_matched_offers"
}
}
},
"competitor_product_domain_id": "67890",
"channel_competitor_id": 3102,
"match_source": "both",
"rule": {
"rule": {
"id": 8,
"name": "Match the cheapest",
"execution_mode": "scheduled",
"next_execution_at": "2026-10-17T06:00:00Z"
},
"result": {
"id": 49654833,
"status": "pending_approval",
"price_incl": "435.00",
"price_excl": "362.50",
"currency": "EUR",
"original_price_incl": "449.00",
"is_approved": false,
"approval_reason": "above_auto_approve_range",
"min_price_applied": true,
"min_price_value": "362.50",
"max_price_applied": false,
"max_price_value": null,
"status_message": null,
"created_at": "2026-10-16T08:43:18Z"
},
"excluded_reason": null
}
}
],
"trackable_channels": [
{
"channel_id": 203,
"channel_competitor_id": 3201
}
],
"page": null
}Marketplace seller offers carry relationship.seller_name. Responses support ETags and use Cache-Control: private, no-cache.
Recent prices of one offer
GET /v1/channels/{channel_id}/products/{product_domain_id}/offers/{competitor_product_domain_id}/history?days=30 returns the page's observed prices (the special price when set, otherwise the regular price, incl. VAT) converted to the channel currency, oldest first. days accepts 1 to 30. A page that is not a matched offer of the product returns 404 offer_not_found.
{
"period_days": 30,
"currency": "EUR",
"points": [
{
"date": "2026-09-20T08:00:00Z",
"price": "120.00"
},
{
"date": "2026-10-01T08:00:00Z",
"price": "108.00"
}
]
}Price history window
GET /v1/channels/{channel_id}/products/{product_domain_id}/history?range=2w&basis=incl returns what the companion's history window draws for one of your products: your price, one line per matched competitor offer, the eMAG buy box with who held it, and your own eMAG offer. range is 1w, 2w (default), 1m, 2m, 3m, 6m or 12m, ending today (UTC) and including it; basis is incl (default) or excl VAT. Up to 2m the resolution is observation, every crawl; from 3m it is week, the last observation of each Monday-aligned UTC week. Prices are in the channel currency. A product that is not in the channel returns 404 product_not_found.
{
"range": "2w",
"from": "2026-10-06T00:00:00Z",
"to": "2026-10-19T23:59:59Z",
"resolution": "observation",
"currency": "EUR",
"basis": "incl",
"series": [
{
"key": "own",
"role": "own",
"offer_id": null,
"domain": "own.example",
"seller_name": null,
"color": "#6366f1",
"set_aside": null,
"ends_at": null,
"points": [
{
"t": "2026-10-06T07:12:00Z",
"price": "115.00",
"regular": "115.00"
},
{
"t": "2026-10-13T07:10:00Z",
"price": "112.00",
"regular": "112.00"
}
]
},
{
"key": "buybox:67891",
"role": "buy_box",
"offer_id": "v1.WzIwMiwiMTIzNDUiLCI2Nzg5MSIsImVtYWcuYmciLCJtYXJrZXRwbGFjZV9zZWxsZXIiLG51bGwsbnVsbCwiZU1BRyJd",
"domain": "emag.bg",
"seller_name": "eMAG",
"color": "#9fe029",
"set_aside": null,
"ends_at": null,
"own_seller_configured": true,
"holders": [
{
"from": "2026-10-06T07:55:00Z",
"to": "2026-10-10T09:30:00Z",
"vendor": "eMAG",
"is_own": false
},
{
"from": "2026-10-10T09:30:00Z",
"to": "2026-10-14T07:55:00Z",
"vendor": "Example Shop",
"is_own": true
},
{
"from": "2026-10-14T07:55:00Z",
"to": null,
"vendor": "eMAG",
"is_own": false
}
],
"points": [
{
"t": "2026-10-06T07:55:00Z",
"price": "112.00",
"regular": "112.00"
},
{
"t": "2026-10-10T09:30:00Z",
"price": "109.90",
"regular": "109.90"
},
{
"t": "2026-10-14T07:55:00Z",
"price": "106.99",
"regular": "106.99"
},
{
"t": "2026-10-19T05:50:00Z",
"price": "106.99",
"regular": "106.99"
}
]
},
{
"key": "own_marketplace:67891",
"role": "own_marketplace",
"offer_id": "v1.WzIwMiwiMTIzNDUiLCI2Nzg5MSIsImVtYWcuYmciLCJtYXJrZXRwbGFjZV9zZWxsZXIiLG51bGwsbnVsbCwiRXhhbXBsZSBTaG9wIl0",
"domain": "emag.bg",
"seller_name": "Example Shop",
"color": "#6366f1",
"set_aside": null,
"ends_at": null,
"points": [
{
"t": "2026-10-06T07:55:00Z",
"price": "111.50",
"regular": "111.50"
},
{
"t": "2026-10-10T09:30:00Z",
"price": "109.90",
"regular": "109.90"
},
{
"t": "2026-10-14T07:55:00Z",
"price": "109.90",
"regular": "109.90"
},
{
"t": "2026-10-19T05:50:00Z",
"price": "109.90",
"regular": "109.90"
}
]
},
{
"key": "v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0",
"role": "competitor",
"offer_id": "v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0",
"domain": "shop.example",
"seller_name": null,
"color": "#e029cd",
"set_aside": null,
"ends_at": null,
"points": [
{
"t": "2026-10-06T06:10:00Z",
"price": "108.00",
"regular": "120.00"
},
{
"t": "2026-10-13T06:05:00Z",
"price": "108.00",
"regular": "120.00"
}
]
}
],
"summary": {
"comparable_count": 4,
"average_now": "107.70",
"lowest": {
"offer_id": "v1.WzIwMiwiMTIzNDUiLCI2Nzg5MSIsImVtYWcuYmciLCJtYXJrZXRwbGFjZV9zZWxsZXIiLG51bGwsbnVsbCwiTWFya2V0IFNlbGxlciJd",
"price": "105.90",
"since": "2026-10-14T07:55:00Z"
},
"highest": {
"offer_id": "v1.WzIwMiwiMTIzNDUiLCI2Nzg5MSIsImVtYWcuYmciLCJtYXJrZXRwbGFjZV9zZWxsZXIiLG51bGwsbnVsbCwiZU1BRyJd",
"price": "112.00",
"since": "2026-10-06T07:55:00Z"
}
},
"special_prices": [
{
"key": "v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0",
"discount_percent": "10.0",
"from": "2026-10-01T08:00:00Z",
"to": null
}
],
"events": [
{
"at": "2026-10-14T07:55:00Z",
"key": "buybox:67891",
"type": "buy_box_change",
"from": "109.90",
"to": "106.99",
"promo": null,
"from_vendor": "Example Shop",
"to_vendor": "eMAG",
"from_is_own": true,
"to_is_own": false,
"own_price": "109.90"
},
{
"at": "2026-10-14T07:55:00Z",
"key": "buybox:67891",
"type": "price_drop",
"from": "109.90",
"to": "106.99",
"promo": null
},
{
"at": "2026-10-13T07:10:00Z",
"key": "own",
"type": "price_drop",
"from": "115.00",
"to": "112.00",
"promo": null
},
{
"at": "2026-10-10T09:30:00Z",
"key": "buybox:67891",
"type": "buy_box_change",
"from": "112.00",
"to": "109.90",
"promo": null,
"from_vendor": "eMAG",
"to_vendor": "Example Shop",
"from_is_own": false,
"to_is_own": true,
"own_price": "109.90"
},
{
"at": "2026-10-10T09:30:00Z",
"key": "buybox:67891",
"type": "price_drop",
"from": "112.00",
"to": "109.90",
"promo": null
},
{
"at": "2026-10-10T09:30:00Z",
"key": "own_marketplace:67891",
"type": "price_drop",
"from": "111.50",
"to": "109.90",
"promo": null
}
],
"events_truncated": false
}ownYour shop's price, keyed own. Out-of-stock prices stay drawn, as on Pricemind's own price line.
competitorOne line per matched non-marketplace offer, keyed by its offer_id, the same id as in resolve's offers. Other marketplace pages get a line from the page price.
buy_boxOne line per eMAG page (emag.bg, emag.ro, emag.hu) from the page price, keyed buybox:{page product_domain_id}. holders says who held the buy box crawl by crawl, also in weekly windows; the current holder's interval has to: null. own_seller_configured says whether your eMAG seller name is set on the channel. Other sellers on the page have no line.
own_marketplaceYour seller's offer on that eMAG page, keyed own_marketplace:{page product_domain_id}, present only when your seller name is set and you were on the page in the window. Once you have left the page, offer_id is null and set_aside is no_price.
Points are in-stock observations with a price, oldest first; a line is never filled across a gap. set_aside follows the same rule as resolve's offers (out_of_stock, stale, not_comparable or no_price), and ends_at is the last good point of a line that stops. color is Pricemind's chart colour; your own lines are always #6366f1.
summary covers the same comparable offers as the panel's verdict, including eMAG sellers without a line and your own seller row: comparable_count, average_now, and lowest and highest over the window. Each extreme carries the offer_id to name it from resolve's offers and since, when that offer's run at the price began. special_prices lists the periods below the regular price; a special that was already running starts before the window's from.
events are newest first: price_drop and price_up (with promo started or ended), out_of_stock, back_in_stock and buy_box_change, which adds from_vendor, to_vendor, whether each is you, and own_price, your eMAG price at that crawl. Changes at the window's first observation compare with the last observation in the 30 days before it. At most 500 events are returned; events_truncated says there were more. The payload carries no labels, so your client words everything.
What the pricing rule will do
GET /v1/channels/{channel_id}/products/{product_domain_id}/rule-suggestion returns the rule result that decides the product's price, chosen like the rule engine: an active campaign pricing the product wins over every rule; otherwise the highest-priority active rule whose latest result sets a price (calculated, or pending_approval until someone approves it in Pricemind); otherwise the highest-priority rule that skipped or failed, with its status_message. Superseded and rejected results never count.
{
"rule": {
"id": 8,
"name": "Match the cheapest",
"execution_mode": "scheduled",
"next_execution_at": "2026-10-17T06:00:00Z"
},
"result": {
"id": 49654833,
"status": "pending_approval",
"price_incl": "435.00",
"price_excl": "362.50",
"currency": "EUR",
"original_price_incl": "449.00",
"is_approved": false,
"approval_reason": "above_auto_approve_range",
"min_price_applied": true,
"min_price_value": "362.50",
"max_price_applied": false,
"max_price_value": null,
"status_message": null,
"created_at": "2026-10-16T08:43:18Z"
},
"excluded_reason": null
}original_price_incl is the price when the rule ran, so the change is price_incl minus it. min_price_applied and max_price_applied say the floor or ceiling moved the price; their values are excl. VAT, as configured on the rule. rule.execution_mode picks the wording: scheduled runs at next_execution_at (a target time, after the channel index is ready), auto after each index refresh, manual when someone starts it. next_execution_at is null for auto and manual rules.
When no rule decides the price, rule and result are null and excluded_reason is no_rule (the channel has no active rule), in_campaign (an active campaign prices the product) or not_in_scope (active rules have no current result for it).
Add a page to one of your products
On an unmatched or not_tracked page of a shop that is a competitor of the channel, a person can add the page to one of their products. It is Pricemind's manual URL check, with the same statuses and copy as the app:
- Find the product with
GET …/products/search?q=(name, SKU, EAN or a custom field; at least 3 characters, otherwise400 query_too_short). - Start the check with
POST …/manual-url-requestsand{"url", "product_domain_id"}. It answers202with the workflow. A shop that is not a competitor of the channel returns422 competitor_not_configured; add it in Pricemind first. - Poll
GET …/manual-url-requests/{request_id}whilein_progress. Whencan_confirm, show thepreviewfor the person to compare with their product. - Send
POST …/confirmwith the reviewedversion, orPOST …/cancelfor “not this product”. Once the channel is reindexed, shortly after, the page appears as a matched offer in resolve.
curl --get 'https://api.pricemind.io/v1/channels/202/products/search' \
--header "X-API-Key: $PRICEMIND_API_KEY" \
--data-urlencode 'q=kettle'
curl 'https://api.pricemind.io/v1/channels/202/manual-url-requests' \
--header "X-API-Key: $PRICEMIND_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url":"https://shop.example/product/0001","product_domain_id":"12345"}'
curl 'https://api.pricemind.io/v1/channels/202/manual-url-requests/3f6c1d2e-8a4b-4c5d-9e7f-0a1b2c3d4e5f' \
--header "X-API-Key: $PRICEMIND_API_KEY"
curl 'https://api.pricemind.io/v1/channels/202/manual-url-requests/3f6c1d2e-8a4b-4c5d-9e7f-0a1b2c3d4e5f/confirm' \
--header "X-API-Key: $PRICEMIND_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"version":3}'{
"id": "3f6c1d2e-8a4b-4c5d-9e7f-0a1b2c3d4e5f",
"state": "ready_for_review",
"version": 3,
"submitted_url": "https://shop.example/product/0001",
"preview": {
"product_domain_id": 67890,
"title": "Synthetic example kettle",
"url": "https://shop.example/product/0001",
"domain": "shop.example",
"image": "https://shop.example/images/0001.jpg",
"codes": [
{
"name": "EAN",
"value": "0012345678905"
}
],
"brand": "Example Brand",
"price": "99.00",
"currency": "EUR",
"availability": 1,
"observed_at": "2026-10-16T08:00:00Z",
"code_matches": [
"EAN"
]
},
"headline": "Product ready — your turn",
"detail": "Check this is the right product, then confirm the match.",
"progress": 88,
"can_confirm": true,
"can_retry": false,
"terminal": false,
"in_progress": false,
"failure": null
}Crawl failures (dispatch_failed, completed_without_product, failed, timed_out) are reported in failure with Pricemind's title and message, not as HTTP errors; offer POST …/retry with the current version when can_retry. A stale version returns 409 request_changed: read the status and offer the action again. The check and the confirmed match are recorded under the person acting: the signed-in person for a browser credential, otherwise the account.
Errors
Every error uses {"error": {"code", "message", "details"}}; details.parameter names a rejected input. Keep the X-Request-ID header for support.
400invalid_url, url_too_long, query_too_short or invalid_input.
401 unauthorizedMissing, invalid, revoked or expired credential; sign in again.
403insufficient_scope (a scope is missing), subject_inactive (the person the credential belongs to was removed or deactivated in the account) or channel_access_denied (the channel is not in the account).
404product_not_found, offer_not_found or request_not_found.
409Page check conflicts: request_changed, request_not_ready, request_not_retryable, target_already_exact_match, target_product_not_found, competitor_not_available. The message is the app's own copy.
422 competitor_not_configuredThe page's shop is not a competitor of the channel.
429 rate_limitedThe credential's hourly limit is reached; keep the last result and respect Retry-After.
502 / 503 / 504confirmation_failed (try again), upstream_unavailable, representation_unavailable or upstream_timeout; respect Retry-After.
See rate limits and errors.