> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://tieback.io/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tieback.io/docs/_mcp/server.

# GS1 Digital Link Contract

> The GS1 Digital Link URL contract used by tieback resolvers, covering supported application identifiers, path order, normalisation and redirect behaviour.

This page defines the URL structures **tie*back*** 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, **tie*back*** 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

**tie*back***

supports two activation modes for minted units:

| Mode              | Behaviour                                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Active at mint    | The unit is active the moment it is issued. Scans resolve normally.                                                                    |
| Manual activation | The 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:

| Condition                         | Cache-Control          |
| --------------------------------- | ---------------------- |
| Activation state recently changed | `no-store, max-age=0`  |
| Stable resolution                 | `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 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?

**tie*back***

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 telemetry is triggered.

## Related Docs

* [Resolver and GS1 Digital Link](/product-module/resolver-gs-1-digital-link)
* [Product Identifiers in **tie*back***](/product-module/identifiers)
* [Minting Overview](/minting/overview)
* [Architecture](/getting-started/architecture)