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
ReadGET /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.
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:
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.
Create links and find competitor products
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:
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.
