Compare your own catalog to the market

Produce a reviewable comparison: which of your SKUs match market products, which have available competitor offers, and which observed market products are absent from your complete catalog. Finish with a decision list, not an automatic price change or purchasing order.

Start with a sandbox key in an isolated workspace. For your own live catalog, use a live key with merchant:write, intelligence:read and catalog:read plus the comparisons:access entitlement. Prepare the complete catalog for the chosen market: unique SKU, canonical ID or valid GTIN, actual observation/expiry times, currency and tax basis. Prepare curl and a private CATALOG_REQUEST_KEY. The market source owner must supply fresh evidence; importing your catalog does not import market data.

Catalog import replaces the current projection; it is not an append operation. Do not upload a sample or a single page of a larger catalog and interpret the remaining market products as real assortment gaps. If your full catalog exceeds the supported import bound, stop and resolve that product limitation. Live batch reads are metered; test data is representative, not current market evidence.

PUT /v1/merchant/catalog accepts up to 1,000 items with unique merchant_sku values and exact canonical IDs or valid GTINs. Use merchant:write, the comparisons:access subscription entitlement and an Idempotency-Key. The market source does not need to exist yet. Supply actual source observation and expiry times, market, currency and tax_basis; do not copy example timestamps as live evidence. Replacing the catalog advances its source observation time. Your commerce system remains authoritative.

{
  "evidence": {
    "source_id": "merchant-export",
    "source_ref": "merchant:export:example",
    "observed_at": "2026-09-29T08:00:00Z",
    "expires_at": "2026-09-30T08:00:00Z",
    "market": "FI",
    "currency": "EUR",
    "tax_basis": "inclusive"
  },
  "items": [
    {
      "merchant_sku": "headphones-black",
      "canonical_product_id": "sony_wh1000xm5_black",
      "current_price": 249,
      "unit_cost": 160,
      "fulfillment_cost": 5,
      "delivery_charge": 5,
      "minimum_margin_percent": 20
    }
  ]
}

# Use a private sandbox key and an isolated workspace first.
# catalog.json must contain YOUR complete catalog and current source evidence.
curl --fail-with-body --silent --show-error -X PUT https://hintadata.fi/v1/merchant/catalog \
  -H "Authorization: Bearer $HINTADATA_API_KEY" \
  -H "Idempotency-Key: $CATALOG_REQUEST_KEY" \
  -H 'Content-Type: application/json' --data-binary @catalog.json

Write the body to catalog.json and set a new request key for this replacement. Verify imported equals the number of submitted items and the returned evidence matches your export. Retrying identical content uses the same key. Never advance timestamps merely to make old data appear fresh.

GET /v1/merchant/coverage requires intelligence:read and consumes no comparison credits. It reports both sources as missing, stale or fresh and counts matched, ambiguous and unmatched rows. Filter rows with resolution and paginate with limit/offset. Missing market evidence is not evidence that competitors do not sell a product. An ambiguous GTIN remains ambiguous; correct the source identity or supply an exact canonical ID.

curl --fail-with-body --silent --show-error 'https://hintadata.fi/v1/merchant/coverage?limit=100&offset=0' \
  -H "Authorization: Bearer $HINTADATA_API_KEY"

Require both market_status and merchant_status to be fresh before interpreting the comparison. Read every coverage page using next_offset until it is null. Keep unmatched and ambiguous rows on a separate correction list; do not discard them to improve the apparent coverage.

POST /v1/products/resolve and POST /v1/offers/batch require catalog:read. Each accepts 1–100 items, each with exactly one canonical_product_id, gtin or merchant_sku. Results preserve order and include per-item status and candidate IDs. Valid GTIN-8/12/13/14 strings are zero-normalized; invalid check digits reject the request. These are read-only POSTs without Idempotency-Key. Live batches cost one comparison credit per input, including unmatched results; failed requests release their reservation. Test mode is free and representative.

{"items":[{"merchant_sku":"headphones-black"},{"canonical_product_id":"sony_wh1000xm5_black"}]}

Resolve your merchant_sku batches, inspect every per-item status and fetch offers for resolved rows. Save the link between each SKU, canonical ID and source evidence. The exercise below demonstrates matched/unmatched handling with representative canonical IDs; it does not import your catalog or prove live assortment completeness.

Once the complete catalog is fresh and every identity is matched, request assortment opportunities and follow next_offset through all pages. A 409 catalog_unresolved means identity repair is still required. Save canonical_product_id, observed_stores, available_supplier_count, interpretation and evidence for each candidate. A successful empty list means no gaps in this supplied market snapshot, not universal market coverage.

curl --fail-with-body --silent --show-error 'https://hintadata.fi/v1/assortment/opportunities?limit=100&offset=0' \
  -H "Authorization: Bearer $HINTADATA_API_KEY"

Create three review groups in your own system: comparable offers, unresolved evidence, and observed assortment-gap candidates. Include source timestamps and money basis. Approve any commercial action separately. If you also request pricing recommendations, supply all cost fields and inspect status and evidence_gaps before using a recommendation.

You have an import receipt for the intended complete catalog, coverage counts reconciled with its rows, an explicit status for each requested SKU, and paginated assortment candidates with source evidence. All unresolved identities have an owner and next action. If freshness or identity checks fail, the correct result is a blocked decision with a correction list, not a fabricated comparison.

Search min_price and comparison best_offer use available delivered prices, not sticker prices. Null means no known available offer, not zero. Compare no longer accepts goal or range; use history for a time window. Pricing returns your current item price, suggested item price, delta, minimum price and proposed margin. Costs include fulfillment and delivered revenue includes delivery_charge. All inputs need compatible market, currency and known tax basis. Missing fields or stale merchant evidence produce insufficient_evidence with evidence_gaps. This API call returns a recommendation. Hintadata’s automatic repricing updates store prices according to the configured pricing rules and margin limits. Assortment requires a fresh, fully resolved catalog and reports observed gaps, never demand forecasts.

An observed gap is only a product present in the supplied market data but absent from your imported catalog. It is not demonstrated customer demand, profitable sourcing or permission to buy stock. Missing or unknown availability is not sold out. An offer list can contain unavailable offers; use the available delivered-price comparison and retain its evidence.

POST /v1/watchlists requires an explicit condition. target_price triggers at or below a threshold; below_own_price compares to the matched merchant SKU including delivery. Both notify when the condition becomes true. price_change_percent measures absolute change from the preceding accepted snapshot; availability_change only reports known available/unavailable transitions. Missing evidence is never sold out. New watches do not immediately send. GET supports status and canonical_product_id filters and pagination. POST /v1/watchlists/batch atomically pauses, resumes or deletes up to 100 distinct IDs with expected_revision and Idempotency-Key. Any conflict rejects the entire batch. Replacing the merchant catalog invalidates pending below-own-price decisions.

{"canonical_product_id":"sony_wh1000xm5_black","condition":"price_change_percent","change_percent":5,"channel":"webhook"}

400 invalid_request: check unique SKUs, exactly one identifier per batch row, GTIN check digits and evidence times. 401/403: correct the credential, scope or entitlement; never include the key in a support ticket. 409 source_conflict: reconcile the source ID and export order; do not relabel stale data. 409 idempotency_conflict: reuse a key only with its original body.

Unmatched or ambiguous: repair source identities, review candidates and re-import the complete catalog with genuinely newer evidence. 409 catalog_unresolved: complete that repair before assortment analysis. Missing/stale coverage or 503 source_unavailable/source_stale: have the relevant source owner refresh the data, then repeat coverage. Never replace these failures with a successful empty result.

429 or temporary 5xx: respect Retry-After and use bounded retries; preserve the import request key and body. If interrupted after import, inspect coverage before retrying. There is no undo command for catalog replacement: restore from your authoritative commerce export with valid newer evidence. For the next task, see the price-watch lifecycle guide; creating watches is a separate write.