> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create, review and remove matches

> Use an API key to create links, reject or update reviews, and remove matches.

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`](https://docs.retailgrid.io/api-reference/matching/list-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`.

```json theme={null}
{
  "decisions": [{
    "match_id": "m1_example",
    "version": 1,
    "revision": 0,
    "evidence": "0123456789abcdef0123456789abcdef",
    "action": "reject",
    "note": "Wrong product"
  }]
}
```

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:

```json theme={null}
{
  "match_ids": ["m1_example"],
  "expected_versions": {"m1_example": 1}
}
```

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.

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

```json theme={null}
{
  "pairs": [{"rg_item_id": "SKU-1", "competitor_product_id": "listing-id", "relation": "direct"}]
}
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.