Skip to main content
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 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.