Resolver

What It Does

The Resolver provides public endpoints that map product identifiers to the correct Digital Product Passport destination. It powers the GS1 Digital Link scan path and is the entry point for all QR, NFC, and RFID scans.

Who It’s For

Systems that need to resolve a barcode or identifier to a tieback product reference without authentication.

Resolve Identifier

Resolves a product identifier to a destination URL and optionally activates a token on first scan.

Authentication: None required. The resolver is a public endpoint.

Inputs

Resolution Strategy

1. Tenant validation — the hostname is mapped to a brand via a verified custom domain or platform subdomain.
2. Non-GS1 fallback — if a fallback type and ID are provided, resolves directly by entity ID (with brand ownership check).
3. GS1 serial — if GTIN + serial are provided, resolves to the specific token.
4. GS1 lot — if GTIN + lot are provided, resolves to the lot.
5. GTIN-only — resolves to the product (active identifiers first, with retired fallback).

First-Scan Activation

If the resolved token has first-scan activation enabled and has not yet been scanned, it is activated on its first valid scan. This is idempotent — repeated scans do not re-trigger activation. Concurrency is handled safely to prevent duplicate activations.

Response

1
{
2
  "ok": true,
3
  "outcome": "resolved",
4
  "destination_url": "/p/<passport-id>",
5
  "activation_effect": "just_activated | already_active | not_applicable",
6
  "cache_policy": "no_store | cache_public_3600"
7
}

Error responses return { "ok": false, "outcome": "brand_not_found" | "not_found" }.

Cache-Control Semantics

The edge layer uses the cache policy to set HTTP headers:

• no_store → Cache-Control: no-store, max-age=0 (used after activation or when a token is pending activation)
• cache_public_3600 → Cache-Control: public, max-age=3600 (used for already-active or standard resolutions)

Scan Telemetry

Scan events are recorded asynchronously after each resolution. Telemetry does not block or delay the consumer redirect.

Recorded data includes:

• Resolved product and token references
• Original request path and query parameters
• GDPR-safe truncated IP address
• Geographic information (country, with region and city captured where available)
• User agent metadata, including a parsed summary (browser family, operating system, device class)
• Traffic classification: human, link-preview unfurler, crawler, or unknown
• Resolution outcome

Traffic classification. Each resolved scan is classified into a traffic class so that human activity, link-preview unfurlers, and search crawlers can be reported separately. Classification is conservative and based on the request’s user agent. Unknown traffic is treated as non-bot for activation, but is reported distinctly in analytics.

Privacy. IP addresses are truncated before storage. The parsed user-agent summary contains only coarse browser, OS, and device fields. No personally identifiable information is retained beyond what is required for aggregate analytics.

Legacy Resolver

The original resolution endpoint remains available for backward compatibility. It resolves a product identifier to a product reference using the brand’s platform subdomain.

Inputs:

Returns: The product reference on match, or null if not found.

Minimal Disclosure

The resolver returns only a destination URL or product reference. No product name, description, pricing, or other data is exposed. This is by design — the resolver is a routing primitive, not a data endpoint.

Limits & Notes

• Public access — no authentication is required.
• GTIN normalisation — GTIN values are normalised to digits only before resolution.
• Brand-scoped — resolution is scoped to the brand identified by the hostname.
• Fallback IDs — must be valid UUID strings. Invalid values return not_found.

FAQ