For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Getting Started
    • Introduction
    • Getting Started
    • Tia — Operations Assistant
    • Architecture
    • Security Architecture
  • Onboarding & Plans
    • Onboarding Overview
    • Plans & Subscriptions
    • Tia Credits
  • Tenancy & Governance
    • Roles & Members
    • Audit Log
    • Notifications
    • Economic Operators
  • Authoring Studios
    • Content Studio
    • Theme Studio
    • Advanced Studio (Track B)
  • Product Module
    • Products
    • Custom Fields
    • Global Search
    • Identifiers
    • Product Import
    • Bulk Editing
    • Bulk Updates
    • Resolver & GS1 Digital Link
    • GS1 Digital Link Contract
  • Localisations
    • Overview
    • Market Packs
    • Multilingual Content
  • Domains & Custom Hostnames
    • Domain Architecture
    • Resolver Domain Flow
    • Custom Hostname Setup
    • DNS Setup Guide
    • Resolver & Passport Rendering
    • Custom Hostname Lifecycle
    • Troubleshooting
  • Passports
    • Overview
    • Passport Operations
    • Lifecycle States
    • Controlled Update & Break-Glass
    • Content & Templates
    • Themes & Presentation
    • Consumer Experience
    • Publication Lifecycle
    • Brand Setup & Readiness
    • Drafts
  • Passport Intelligence
    • Passport Intelligence
    • Intelligence Overview
    • Scan Visibility
    • Trust Signals
    • Engagement Insights
    • Investigation Timelines
    • Data & Privacy
    • Roadmap
  • Minting
    • Overview
    • Lifecycle
    • Architecture
    • Limits & Performance
    • Token Preview
    • Exports & Print Jobs
    • Carrier Output Profiles
    • Bring-Your-Own Serials
    • Security
    • FAQ
  • API Reference
    • API Credentials Guide
    • API: Credentials
    • API: Products
    • API: Identifiers
    • API: Import
    • API: Batches
    • API: Attachments
    • API: Bulk Updates
    • API: Minting
    • API: Resolver
    • API: Search
On this page
  • Primary Identifier
  • GS1-ready brands
  • Non-GS1 brands
  • Path Qualifiers
  • Examples
  • Query Attributes
  • Example
  • Query Passthrough
  • Activation Modes
  • Cache Behaviour
  • FAQ
  • Related docs
Product Module

GS1 Digital Link Contract

Was this page helpful?
Previous

Localisations Overview

Next
Built with

This page defines the URL structures tieback generates and resolves for GS1 Digital Link, including optional qualifiers and attributes.

Primary Identifier

GS1-ready brands

The GTIN (Global Trade Item Number) is used as the product-level primary key, encoded as AI(01) in the resolver path:

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

Non-GS1 brands

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.

Path Qualifiers

The following GS1 Application Identifiers are supported as path segments:

AINamePath Segment
AI(10)Lot / Batch/10/<LOT>
AI(21)Serial/21/<SERIAL>

Examples

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

Query Attributes

The following GS1 Application Identifiers are supported as query parameters:

AINameFormatExample
AI(11)Production dateYYMMDD?11=250101
AI(17)Expiry dateYYMMDD?17=261231

Example

https://acme.tieback.io/01/05060012345678/10/LOT-A?17=261231

Query Passthrough

Any query parameters not recognised as GS1 AIs are preserved and passed through the redirect. This supports future extensions such as NFC cryptographic payloads:

?picc_data=...&cmac=...

Activation Modes

tieback

supports two activation modes for minted units:

ModeBehaviour
Active at mintThe unit is active immediately upon minting. Scans resolve normally.
First scanThe unit remains in minted status until its first valid scan, at which point it transitions to active. Subsequent scans return already_active.

First-scan activation is idempotent and concurrency-safe.

Cache Behaviour

The Edge Resolver sets HTTP cache headers based on the resolution outcome:

ConditionCache-Control
Unit just activatedno-store, max-age=0
Unit already active or no unit contextpublic, max-age=3600
Not foundno-store, max-age=0

Bot requests (detected via User-Agent) receive a static OpenGraph HTML response and do not trigger activation or telemetry.

FAQ

What is a GTIN?

A GTIN (Global Trade Item Number) is a globally unique product identifier issued by GS1. It is the primary key used in GS1 Digital Link URLs. Common formats include EAN-13, UPC-A, and GTIN-14.

What if my brand does not have a GTIN?

tieback

provides fallback resolver paths using internal identifiers (/mu/, /mb/, /ml/). These work identically to GS1 paths for resolution and activation, and can be upgraded to GS1 paths when a GTIN becomes available.

Are query parameters preserved through redirects?

Yes. All query parameters — including unrecognised ones — are preserved and passed through the resolver redirect. This ensures downstream systems and future NFC integrations receive the full context.

What happens if a bot crawls a scan URL?

Bots are detected via User-Agent inspection and receive a static HTML response with OpenGraph meta tags for link preview rendering. No activation or telemetry is triggered.

Related docs

  • Resolver and GS1 Digital Link
  • Product Identifiers in tieback
  • Minting Overview
  • Architecture