Browser companion

Browser companion

Answer “am I priced right on this page, and what will happen next?” for the shop page a person is looking at: which of your products it belongs to, the matched offers, recent prices and price history, the pricing rule's outcome, and a way to add an unmatched competitor page to one of your products.

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:read

Tracked shop domains.

products:read

Resolve a page, search your products, read a page check.

competitor_prices:read

Matched offers (include=offers), offer history and the price history window.

rule_suggestions:read

The pricing rule outcome (include=rule and the rule-suggestion route).

product_pages:write

Start, 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.

Tracked domains
[
  {
    "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.

Resolve, history and rule
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"
own

The page is one of your channel products. competitor_product_domain_id is null.

competitor

A 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.

unmatched

A known page of a shop you track that none of your products uses yet. page holds what Pricemind collected for it.

not_tracked

An 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.

Resolve response (offers shortened)
{
  "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.

Offer history
{
  "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.

Price history with an eMAG buy box
{
  "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
}
own

Your shop's price, keyed own. Out-of-stock prices stay drawn, as on Pricemind's own price line.

competitor

One 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_box

One 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_marketplace

Your 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 suggestion
{
  "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:

  1. Find the product with GET …/products/search?q= (name, SKU, EAN or a custom field; at least 3 characters, otherwise 400 query_too_short).
  2. Start the check with POST …/manual-url-requests and {"url", "product_domain_id"}. It answers 202 with the workflow. A shop that is not a competitor of the channel returns 422 competitor_not_configured; add it in Pricemind first.
  3. Poll GET …/manual-url-requests/{request_id} while in_progress. When can_confirm, show the preview for the person to compare with their product.
  4. Send POST …/confirm with the reviewed version, or POST …/cancel for “not this product”. Once the channel is reindexed, shortly after, the page appears as a matched offer in resolve.
Search, start, poll and confirm
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}'
Workflow ready for review
{
  "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.

400

invalid_url, url_too_long, query_too_short or invalid_input.

401 unauthorized

Missing, invalid, revoked or expired credential; sign in again.

403

insufficient_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).

404

product_not_found, offer_not_found or request_not_found.

409

Page 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_configured

The page's shop is not a competitor of the channel.

429 rate_limited

The credential's hourly limit is reached; keep the last result and respect Retry-After.

502 / 503 / 504

confirmation_failed (try again), upstream_unavailable, representation_unavailable or upstream_timeout; respect Retry-After.

See rate limits and errors.