Product Module

GS1 Digital Link Contract

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 the moment it is issued. Scans resolve normally.
Manual activationThe unit is issued inactive and stays in minted status until the brand activates it, for example when it is packed, shipped or sold.

Activation is a brand controlled decision. Scanning a code never changes the activation state of a unit.

Cache Behaviour

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

ConditionCache-Control
Activation state recently changedno-store, max-age=0
Stable resolutionpublic, 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 telemetry.

FAQ

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.

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.

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.

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