Product Module

Resolver and GS1 Digital Link

This page explains how tieback resolves product identifiers using GS1 Digital Link. The resolver connects a physical identifier (such as GTIN/EAN/UPC) to a structured Digital Product Passport record. It ensures consistent routing, market-aware presentation, and controlled lifecycle visibility across product scans.

What It Does

The tieback Resolver provides a permanent, public URL for every product identifier. When a barcode is scanned or a link is followed, the resolver maps the identifier to the correct product — even if the identifier has since been retired.

Who It’s For

Supply chain participants, consumers scanning product codes, and systems integrating with GS1 Digital Link standards.

How It Works

Permanent Brand Domain

Every brand on tieback is assigned a permanent resolver subdomain:

<brand-subdomain>.tieback.io

This is the canonical domain for all public scan paths. It does not change, even if the brand’s display name is updated.

The resolver supports the GS1 Digital Link URI structure:

https://<brand>.tieback.io/01/<GTIN>

Optional path segments are also supported:

  • /10/<batch> — batch/lot number
  • /21/<serial> — serial number

Example:

https://acme.tieback.io/01/05060012345678
https://acme.tieback.io/01/05060012345678/10/LOT-A/21/001

Non-GS1 Fallback Paths

For brands that are not yet GS1-ready, tieback supports internal identifier paths:

PatternDescription
/mu/<MINT_UNIT_ID>Resolve by mint unit ID
/mb/<MINT_BATCH_ID>Resolve by mint batch ID
/ml/<MINT_LOT_ID>Resolve by mint lot ID

These IDs are UUIDs. The resolver validates that the entity belongs to the brand identified by the host header.

Resolution Strategy

The resolver uses a deterministic fallback strategy:

  1. Active identifier first — if the GTIN is currently active on a product, it resolves immediately.
  2. History fallback — if no active match exists, the resolver falls back to the most recently retired match.
  3. UUID only — the resolver returns the product’s UUID only. No product data is exposed publicly.

The resolved product ID is used to redirect to /p/<product-id>.

First-Scan Activation

For mint units with activation_mode = first_scan, the resolver activates the unit on its first valid scan:

  • The unit transitions from minted to active
  • Activation is idempotent — subsequent scans return already_active
  • Concurrency is handled safely to prevent duplicate activations
  • Activation does not depend on telemetry succeeding

Cache-Control Behaviour

The Edge Worker sets HTTP cache headers based on the resolver response:

ConditionCache-Control
Unit just activated (just_activated)no-store, max-age=0
Unit already active or no unitpublic, max-age=3600
First-scan mode, not yet activatedno-store, max-age=0

Wrong Domain Behaviour

If a scan request arrives on a platform host (e.g. app.tieback.io, docs.tieback.io, or the root tieback.io), the resolver does not process it. These hosts serve the application, documentation, or marketing site respectively — not product resolution.

Query String Preservation

Any query parameters appended to the scan URL are preserved through the redirect. This allows downstream systems to pass tracking or context parameters.

Architecture

The resolver operates in two layers:

  1. Backend resolution engine — server-side logic that validates identifiers, resolves products, handles first-scan activation, and records telemetry.
  2. Edge network — a globally distributed edge layer that intercepts scan routes (/01/*, /mu/*, /mb/*, /ml/*), forwards them to the resolution engine, and returns the appropriate redirect to the consumer.

Edge Behaviour

  • Bot detection: Known bots and link unfurlers receive a static OpenGraph HTML response for preview cards, without triggering activation or telemetry.
  • Telemetry: Scan events are recorded asynchronously and do not delay the consumer redirect.
  • Privacy: IP addresses are truncated before storage in compliance with GDPR requirements.
  • Cache-Control: HTTP cache headers are set dynamically based on the resolution outcome — freshly activated units bypass caching, while stable resolutions are cached for performance.

Limits & Notes

  • The resolver is public — no authentication is required.
  • Only the product UUID is returned; no product details, pricing, or sensitive data is disclosed.
  • The resolver supports GTIN-based paths (/01/...) and non-GS1 fallback paths (/mu/, /mb/, /ml/).
  • Batch (/10/...) and serial (/21/...) segments are captured and used for mint unit/lot resolution.
  • Fallback IDs must be valid UUID strings. Invalid UUIDs return not_found.

FAQ

The resolver falls back to the most recently retired match. Old printed codes remain functional — they still resolve to the correct product.

No. The resolver returns only the internal product UUID and issues a redirect. No product names, descriptions, pricing, or other data is disclosed.

Yes. The resolver supports verified custom domains in addition to the permanent brand subdomain on tieback.io.

Scan requests arriving on platform hosts (e.g. the main application or documentation site) are not processed by the resolver. Only the brand’s assigned subdomain or verified custom domain handles resolution.

Tokens with first-scan activation remain inactive until their first valid scan, at which point they transition to active. This is idempotent and concurrency-safe.