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

# Manage Resolution Rules

> Create, read, update, delete and reorder GS1 resolver resolution rules (where a scan of a product, brand or organization is redirected) and read the rule summary — the programmatic equivalent of the dashboard's per-product "Resolver rules" page.

Programmatic equivalent of the dashboard's `products/<gtin>/resolver-rules/list/`
page and the rule editor behind it. A resolution rule decides where a scan of a
GS1 Digital Link (`/01/<gtin>`) is redirected.

## When to use

* A brand owner wants scans of one product (or a whole brand, or the
  organization) to land somewhere other than the default Closient-hosted page:
  a campaign URL, a seasonal promotion, a per-country or per-language page.
* A brand owner wants to change the order rules are checked in, disable a rule
  without deleting it, or remove one.

## The contract

* **Rules choose destinations; content decides link types.** A product's
  linkset (the link types it advertises: `pip`, `productInfo`,
  `ingredientsInfo`, `nutritionalInfo` and so on) is derived from the product's
  content and its brand's data. Creating, editing, reordering or deleting a
  redirect rule never adds or removes a content-derived link type. A rule
  contributes a link type only by pinning one in `link_type` (for example
  `promotion`, `locationInfo`, `faqs`). If a link type is missing from the
  linkset, fix the product's content; more rules will not add it.
* **Most specific scope first.** Scopes are checked serial, lot, product, brand,
  organization; within a scope the lowest `order_index` first; the first rule
  whose criteria all match wins. With no match the scan goes to the brand's
  Closient-hosted page.
* **Criteria narrow a rule.** Link type, time window, country and language are
  ANDed; an unset criterion constrains nothing.

## Auth

`X-API-Key` header or OAuth token with `resolver:write` scope (`resolver:read`
for reads). Reading rules needs view access to the organization; creating,
updating, deleting and reordering need its change permission, and answer `404`
without it.

## Flow

```
GET    /resolver/api/v1/organizations/{organization_id}/resolution-rules
GET    /resolver/api/v1/organizations/{organization_id}/resolution-rules/default
GET    /resolver/api/v1/organizations/{organization_id}/resolution-rules/summary
POST   /resolver/api/v1/organizations/{organization_id}/resolution-rules
POST   /resolver/api/v1/organizations/{organization_id}/resolution-rules/reorder
GET    /resolver/api/v1/resolution-rules/{rule_id}
PUT    /resolver/api/v1/resolution-rules/{rule_id}
DELETE /resolver/api/v1/resolution-rules/{rule_id}
```

* **`GET` list** — every rule of the organization in evaluation order, paginated
  (`{data, pagination}`, page size up to 100). Filter with `scope_type`
  (`ORGANIZATION`, `BRAND`, `PRODUCT`, `BATCH`, `SERIAL`) and `enabled`.
* **`GET` default** — the implicit fallback rule (a redirect to the brand's
  hosted page). It is not a stored row and cannot be edited.
* **`GET` summary** — total, active and inactive counts and a per-destination
  breakdown.
* **`POST` create** — body: `scope_type`, `scope_id`, `order_index`,
  `destination_type` (`HOSTED_PAGE` or `CUSTOM_URL`), `custom_url` (required for
  `CUSTOM_URL`), `on_custom_url_dead` (`SKIP_RULE` or `FALLBACK_TO_HOSTED`), and
  optional criteria (`link_type`, `absolute_start_at` / `absolute_end_at`,
  `annual_start_mmdd` / `annual_end_mmdd`, `days_of_week`, `time_of_day_start` /
  `time_of_day_end`, `timezone`, `location_countries` / `location_regions` /
  `location_cities`). `scope_id` names the scoped entity by its id (the 22-character
  short id or the canonical UUID), never a GTIN, and is not needed at
  `ORGANIZATION` scope. Returns `201` with the rule, including its `id`.
  `order_index` must be unused at that scope.
* **`PUT` update** — changes only the keys you send; `null` clears a nullable
  field.
* **`DELETE`** — permanent. To keep a rule but stop it applying, `PUT`
  `enabled: false` instead.
* **`POST` reorder** — body `{"rules": [{"id": ..., "order_index": ...}]}`, applied
  atomically. Any id outside the organization aborts the whole call with `404`.

## Verify

Re-read the list and the summary, then resolve the product to see the redirect
actually changed: the MCP tool `resolve_gtin` (read-only; it returns
`destination_url` and `matched_rule_scope`), or `GET /01/<gtin>` without
following redirects and reading the `Location` of its 307. A rule that is
enabled but does not win the resolve check is misordered or its criteria do not
match the scan you tested.

## Notes

* A `CUSTOM_URL` rule on a product whose brand claim is not verified is refused
  with `422`: such a product resolves to its Closient-hosted page until the claim
  is verified.
* A rule's `custom_url` is stored as an entry in the organization's custom-URL
  catalog; see `manage-custom-urls`.
* The dashboard's separate "Routing rules" page (conditional query-parameter and
  path rewrites) and the per-product resolver behavior settings have no API.