Resolver Rules¶

When a consumer scans a product's QR code, GTIN1 needs to decide where to send them. Resolver rules give you control over that decision. You can send scanners to GTIN1's built-in product page, or redirect them to your own website -- and you can vary the destination based on time, location, language, and more.

Rule Hierarchy¶

Resolver rules are organized in a hierarchy of scopes, from most specific to most general. When a scan comes in, GTIN1 evaluates rules starting at the most specific level and works upward until it finds a match.

Priority	Scope Level	Applies To
1 (highest)	Serial	A single serialized item
2	Batch	A specific batch or lot
3	Trade Item	A single GTIN (product)
4	Product	A product family
5	Brand	All products under a brand
6	Organization	All products in an organization
7 (lowest)	GTIN1 Global	Platform-wide default

The first matching rule wins. If no rules match at the Serial level, GTIN1 checks Batch, then Trade Item, and so on. This means you can set a broad rule at the Organization level and override it for specific products, batches, or even individual serial numbers.

Example¶

Suppose your organization has these rules:

Organization level: Redirect all scans to https://yoursite.com/products
Brand level (for "Premium Line"): Redirect to https://premium.yoursite.com
Trade Item level (for GTIN 00785034739064): Use GTIN1's hosted page
Batch level (for lot "RECALL-001"): Redirect to your recall page

When a consumer scans a product from lot "RECALL-001", the Batch-level rule matches first and they see the recall page. A different lot of the same product uses the Trade Item rule and sees the GTIN1 hosted page. A product from the "Premium Line" brand (but without a specific Trade Item rule) redirects to the premium site. Everything else goes to the organization's default URL.

Destination Types¶

Each rule specifies one of two destination types:

Hosted Page¶

GTIN1's built-in product information page displays product details, images, nutritional information, certifications, traceability data, and more -- all managed through the GTIN1 dashboard. The hosted page automatically adapts its content based on the qualifier Application Identifiers in the scanned URI.

For example, if the URI includes a batch number (/10/LOT2024A), the hosted page shows lot-specific information. If the product is on the FDA Food Traceability List, the traceability tab displays relevant critical tracking events.

The hosted page also responds to the linkType query parameter. If a URI includes ?linkType=gs1:certificationInfo, the page opens directly to the certifications tab (when available). If the requested tab does not have content for this product, the page falls back to the product information tab.

Custom URL¶

Redirects the scanner to a URL you specify. Use this to send consumers to your own product pages, marketing campaigns, loyalty programs, or any other web destination.

https://yoursite.com/products/olive-oil
https://campaigns.yoursite.com/summer-2025
https://loyalty.yoursite.com/register?product={gtin}

Rule Criteria¶

Rules can include optional criteria that must all match for the rule to fire. If a criterion is not set, it matches everything.

Time Criteria¶

Control when rules are active:

Criterion	Description	Example Use
Absolute start/end	Rule is active during a specific date range	Holiday campaign: Dec 1 to Jan 5
Annual start/end (MM-DD)	Rule is active during the same dates every year	Annual back-to-school promotion
Days of week	Rule is active on specific days	Weekend-only promotion (Saturday and Sunday)
Time of day start/end	Rule is active during specific hours	After-hours redirect to support page

Time criteria are evaluated in the organization's configured routing timezone. All time criteria are ANDed together -- if you set both a date range and days of week, both must match.

Locale Criteria¶

Target rules based on the scanner's language or country:

Criterion	Description	Example Use
Allowed languages	BCP-47 language tags	Send Spanish speakers to `es.yoursite.com`
Allowed countries	ISO 3166-1 alpha-2 country codes	Different product pages per country

Language is determined from the ?lang= parameter or the Accept-Language header. Country is resolved from the scanner's IP address via GeoIP lookup or the ?country= parameter.

Link Type Criteria¶

Match rules based on the ?linkType= parameter in the URI:

?linkType=gs1:pip           -- Product Information Page
?linkType=gs1:recallStatus  -- Recall information
?linkType=gs1:instructions  -- Usage instructions

A rule with allowed link types only matches when the scanned URI requests one of those types.

Product Status Criteria¶

Match rules based on the product's current status:

Status	Description
Active	Product is currently available
Discontinued	Product has been discontinued
Recalled	Product has been recalled
Unknown	Product status is not known

This enables automatic routing -- for example, a rule that redirects recalled products to a recall information page.

Rule Evaluation¶

Within each scope level, rules are evaluated in order of their order_index (lowest first). The first rule whose criteria all match is selected.

Serial rules (order: 0, 1, 2, ...)
  ↓ no match
Batch rules (order: 0, 1, 2, ...)
  ↓ no match
Trade Item rules (order: 0, 1, 2, ...)
  ↓ no match
Product rules (order: 0, 1, 2, ...)
  ↓ no match
Brand rules (order: 0, 1, 2, ...)
  ↓ no match
Organization rules (order: 0, 1, 2, ...)
  ↓ no match
GTIN1 Global rules (default catch-all)

The GTIN1 Global level always has a catch-all rule that directs to the hosted page, so every scan produces a result.

Recall Override¶

High-severity product recalls override the normal rule evaluation entirely. When GTIN1 detects an active high-severity recall that affects the scanned product:

Normal rule evaluation is bypassed
The consumer is redirected to a dedicated recall landing page
The recall landing page displays official recall information, next steps, and links to the regulatory agency's notice

This safety feature ensures that recalled products always show recall information, regardless of any rules configured by the brand or organization.

URL Health Monitoring¶

For rules with custom URL destinations, GTIN1 monitors the health of each URL. The monitoring system tracks:

Whether the URL is currently accessible
The last HTTP status code received
The number of consecutive failures
When the URL was last checked and when the next check is scheduled

Each rule has a configurable failure policy that determines what happens when the custom URL is down:

Failure Policy	Behavior
Skip Rule	Skip this rule and evaluate the next one in the hierarchy
Fallback to Hosted	Redirect to the GTIN1 hosted page instead

This ensures consumers always reach a working destination, even if your website experiences downtime.

Resolution Simulator¶

The Resolution Simulator lets you test how GTIN1 will resolve a Digital Link URI before any real consumer scans it. Enter a GTIN (and optionally a batch, serial number, language, country, and link type) to see:

Which rule would match
What destination the scanner would be sent to
The full evaluation trace showing which rules were checked and why they matched or did not match
The resolved ambient inputs (language, country, link type, timestamp)

The simulator does not create audit log entries, so you can test freely without affecting your analytics.

Tip

Use the simulator after creating or modifying rules to verify that scans will be routed correctly before the changes affect real consumers.

Audit Logging¶

Every resolution decision is logged for explainability and compliance. The audit log records:

A unique scan ID
The scanned GTIN, batch, and serial number
Resolved ambient inputs (language, country, link type)
Which rule matched (or whether a recall override was applied)
The final destination URL
A full evaluation trace showing which rules were considered

This provides a complete audit trail for SOC 2 compliance and enables debugging of resolution behavior.