Skip to main content
Programmatic equivalent of the dashboard’s “Resolver rules” pages — one per product, brand, lot and serial — and the rule editor behind them. A resolution rule decides where a scan of a GS1 Digital Link (/01/<gtin>, or /01/<gtin>/10/<lot> and /01/<gtin>/21/<serial> for one lot or unit) is redirected.

​
When to use

  • A brand owner wants scans of one product (or one lot or serialized unit of it, 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 lot-specific notice.
  • 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. The paths carry no organization: an API key acts on its own organization, and a session or OAuth caller on its only one. A caller in more than one adds ?organization_id=<id> (400 without it); naming an organization the caller cannot see answers 404.

​
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; 204 with no body. 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.

​
Scope shapes

Each dashboard rules page writes rules at one scope. scope_id is the id of the entity that scope names: A lot’s page also lists the LOT_GROUP rules of every lot group it belongs to, and a serial’s page the SERIAL_GROUP rules of its serial groups. Those are shared by every member of the group: change them only when that is what your human asked for. An individual lot or serial rule beats a group rule the lot or serial also matches.

​
Verify

Re-read the list (filtered to the scope_type you wrote) 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. For a lot or serial rule, resolve the link that carries it: /01/<gtin>/10/<lot> or /01/<gtin>/21/<serial>. 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) has no API. A product’s resolver behavior settings and whether it is enrolled in the resolver are manage-resolver-behavior.