Skip to main content
All requests use Authorization: Bearer $RETAILGRID_API_KEY. Writes also require a UUID Idempotency-Key; reuse it with the same request after a timeout. A changed payload with the same key, actor and operation returns 409. Never replace review tokens automatically after a conflict.

Read before deciding

Read GET /v1/matching/matches to obtain each match’s match_id, version, review.revision, and review.evidence. These tokens protect against concurrent edits and changed product evidence.

Reject or update reviews

POST /v1/matching/matches:batch-decide accepts decisions, a list of 1–500 unique match IDs. Each entry uses the existing review actions approve, reject, reopen, or rematch.
Rejection stays visible with review.status = rejected and the API key owner’s actor. It stops feeding grids on their next refresh. To correct classification, approve with relation: "direct" or "substitute". To replace a pair, use action: "rematch" and replacement: {rg_item_id, competitor_product_id, relation}. Reopen a rejected pair before approving or rematching it.

Remove matches

POST /v1/matching/matches:batch-remove accepts 1–500 unique IDs with a positive expected version for every ID:
Removal hides the match from public match reads and stops it feeding grids. Audit history remains. Automatic matching and ordinary snapshot uploads respect the removal decision. Explicitly add or reopen the pair to restore it. Decision and removal batches return 200 with external_org_id, request_id, ordered results, and changed_item_ids. Each result contains index, match_id, outcome, optional result_match_id, and optional code. Outcomes are decided, removed, already_removed, or error. Missing and foreign IDs both return resource_unavailable; stale versions/evidence return match_version_conflict. Valid entries succeed independently. Exact retries replay the complete original result, including errors. A database/service outage aborts the transaction and returns a request-level error. Malformed requests, duplicate IDs, missing versions and more than 500 entries return 422 before writing. Missing/invalid API keys return 401; missing idempotency keys return 422. Refresh and use a new key for an intentional corrected request after a conflict. GET /v1/matching/competitor-products supports query, competitor, availability, and cursor. Follow next_cursor while has_more is true. Use the returned stable competitor_product_id; a SKU or URL is not a substitute. POST /v1/matching/matches:batch-add accepts 1–500 unique pairs:
Relations are direct or substitute. Results report created, restored, or unchanged. Addition preserves the existing atomic contract: one unavailable resource or relation conflict refuses the whole request. Use review decisions to change an existing relation.