GS1 Digital Link Contract | tieback API Documentation

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:

Pattern	Description
`/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:

AI	Name	Path 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:

AI	Name	Format	Example
AI(11)	Production date	`YYMMDD`	`?11=250101`
AI(17)	Expiry date	`YYMMDD`	`?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:

Mode	Behaviour
Active at mint	The unit is active immediately upon minting. Scans resolve normally.
First scan	The 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:

Condition	Cache-Control
Unit just activated	`no-store, max-age=0`
Unit already active or no unit context	`public, max-age=3600`
Not found	`no-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.