Build GS1 Digital Link

The GS1 Digital Link standard (v1.4 / ISO/IEC 18975) encodes Application Identifiers in URL paths instead of barcode element strings, so the same identifier can drive a barcode scan, a deep link, and a web resolver. This skill teaches an agent how to compose a correct Digital Link URI from structured input — the inverse of decode-gs1-ai.

When to use

A consumer-facing surface needs a QR code or URL for a product: packaging, shelf-talker, email receipt, branded resolver page.
An ERP / PIM / TMS system has structured product+lot+serial data and needs to emit GS1 Digital Link strings to label printers or partner feeds.
An agent received a raw GTIN and wants to construct the canonical Closient resolver URL to hand back to a user.

For the inverse — taking a Digital Link URI and parsing it — see decode-gs1-ai.

Anatomy of a Digital Link

https://id.gs1.org/01/09506000134352/10/ABC123/21/SN9999?linkType=gs1:pip
└──────┬──────┘ └──┬──────────────┘ └──┬─────┘ └──┬─────┘ └──────┬──────┘
   host       primary AI + value   qualifier   qualifier      link type

Component	Rules
Host	Any HTTPS host that supports the resolver protocol. `id.gs1.org` is the canonical GS1-managed host; you may use your own domain (e.g. `id.closient.com`, `acme.gtin.one`).
Primary identifier	Exactly one of `/01/<gtin>`, `/00/<sscc>`, `/253/<gdti>`, `/255/<gcn>`, `/401/<ginc>`, `/402/<gsin>`, `/414/<gln>`, `/417/<gln>`, `/8003/<grai>`, `/8004/<giai>`, `/8006/<gctin>`, `/8010/<cpid>`, `/8013/<gmn>`, `/8017/<gsrn>`, `/8018/<gsrn>`.
Qualifiers	Subsequent `/{AI}/{value}` segments that narrow the primary. For a GTIN only `/22/<cpv>`, `/10/<lot>`, `/21/<serial>` (in that order) or `/235/<tpx>` alone.
Data attributes	Every other AI goes in the query string: `?17=300901` for expiry, `?15=271231` for best-before. Never in the path.
`linkType=`	Tells the resolver what kind of destination to serve (PIP, product page, instructions, recall, etc.).

Step 1 — Validate inputs

Before composing anything, normalize:

def gtin14(raw: str) -> str:
    """Pad to 14 digits and verify the GS1 Mod-10 check digit."""
    digits = raw.strip().zfill(14)
    assert digits.isdigit() and len(digits) == 14, "GTIN must be 8-14 digits"
    total = sum(int(d) * (3 if i % 2 == 0 else 1) for i, d in enumerate(reversed(digits[:-1])))
    assert (10 - total % 10) % 10 == int(digits[-1]), "bad GTIN check digit"
    return digits


gtin = gtin14(raw_gtin)   # validates Mod-10 + pads to 14
assert lot is None or len(lot) <= 20
assert serial is None or len(serial) <= 20
# Expiry must be YYMMDD; convert ISO dates first.

Reject silently-malformed GTINs at this step rather than building a URI that fails resolution downstream.

Step 2 — Compose the primary AI

GTIN is the common case:

host = "https://id.gs1.org"
path = f"/01/{gtin}"      # gtin is 14 digits, zero-padded
url  = host + path

For other primary identifiers:

Primary identifier	Path
GTIN-14	`/01/<gtin14>`
SSCC	`/00/<sscc18>`
GRAI (returnable asset)	`/8003/<grai>`
GIAI (individual asset)	`/8004/<giai>`
GLN (location)	`/414/<gln>`
GSIN (shipment)	`/402/<gsin17>`
GINC (consignment)	`/401/<ginc>`

Step 3 — Append qualifier AIs (canonical order)

The GS1 Barcode Syntax Dictionary fixes which AIs may follow a GTIN in the path, and in what order (dlpkey=22,10,21|235):

/01/{gtin}[/22/{cpv}][/10/{lot}][/21/{serial}]
/01/{gtin}/235/{tpx}

Each of 22, 10 and 21 is optional but their order is mandatory, and 235 stands alone. Expiry (17) is not a qualifier: it is a data attribute and goes in the query string (Step 5). Closient’s resolver answers any other path with 400 Bad Request and a JSON body naming the broken rule (non_qualifier_ai_in_path, qualifier_out_of_order, incompatible_qualifiers, duplicate_qualifier). It never reorders and resolves anyway, so emit the canonical form. (A brand’s custom domain with a hosted dead-end page sends a bad GTIN path to that page instead of the JSON body.)

def append_qualifier(url: str, ai: str, value: str | None) -> str:
    return f"{url}/{ai}/{value}" if value else url

url = host + f"/01/{gtin}"
url = append_qualifier(url, "10", lot)
url = append_qualifier(url, "21", serial)

Step 4 — Encode special characters in values

GS1 Digital Link values are URL path segments, so anything outside the unreserved set (A-Z a-z 0-9 - . _ ~) must be percent-encoded:

from urllib.parse import quote
safe_serial = quote(serial, safe="")  # encode literally everything else
url += f"/21/{safe_serial}"

In practice, lot/serial characters that show up in real life and need encoding: space (%20), + (%2B), & (%26), / (%2F), ? (%3F), # (%23). Don’t pre-escape with \\ — that’s a different encoding.

Step 5 — Attach data-attribute AIs (query string)

AIs that aren’t qualifiers go in the query string as <ai>=<value>:

/01/09506000134352?17=300901&15=271231

Useful examples:

AI	What it means	Example query param
17	Expiry (use-by) date YYMMDD	`17=300901`
15	Best-before date YYMMDD	`15=271231`
16	Sell-by date YYMMDD	`16=271231`
11	Production date YYMMDD	`11=270101`
8005	Price per UoM	`8005=125000`
3922	Price (currency-implied)	`3922=12.50`

Per the spec, query-string AIs should follow data-attribute conventions — not used as primary IDs, never the basis for resolution decisions.

Step 6 — (Optional) attach `linkType` to drive resolution intent

A Digital Link URL can point at one identifier but many destinations: product info page, recall notice, instructions, video, loyalty enrollment. The linkType query string parameter tells the resolver which destination the agent (or end user) wants:

https://id.gs1.org/01/09506000134352?linkType=gs1:pip
https://id.gs1.org/01/09506000134352?linkType=gs1:recallNotice
https://id.gs1.org/01/09506000134352?linkType=gs1:instructions

The IANA-registered link-type vocabulary is the source of truth (see https://www.gs1.org/voc/). Closient’s resolver maps these to hosted-page destinations and the Resolver model’s destination_type column — the resolver API reference lists every link type Closient recognizes. If you don’t set linkType, the resolver returns its default destination — typically the brand’s PIP or the public Closient product page.

Step 7 — Pick the host

Host	Use it when
`https://id.gs1.org`	You want GS1’s official global resolver to handle the URL.
`https://id.closient.com`	You’re publishing through Closient and want our resolver to serve hosted pages, redirects, and analytics.
`https://<brand>.gtin.one`	Closient-managed branded resolver subdomain for a specific brand.
`https://<brand>.example.com`	The brand’s own CNAME pointing at Closient.

Any host that implements the GS1 DL resolver protocol will serve the same identifier. The Closient hosted pages live under id.closient.com and *.gtin.one; the Brand.preferred_resolver_host column stores which one to emit for that brand’s products.

Full example

Inputs:

GTIN-14: 09506000134352
Lot: ABC123
Expiry: 2030-09-01 (= 300901 YYMMDD, AI 17 → query string)
Serial: SN9999
Best-before: 2027-12-31 (= 271231 YYMMDD, AI 15 → query string)
Link type: PIP (product information page)
Host: https://id.closient.com

Canonical URL:

https://id.closient.com/01/09506000134352/10/ABC123/21/SN9999?17=300901&15=271231&linkType=gs1:pip

Compose the path segments in the order shown, percent-encode only the value slots, and convert ISO dates to YYMMDD before emitting ?17=. For a QR Code, any query string (and any lowercase letter) forces byte mode, which makes the symbol roughly a third larger. A code that only needs to identify the item can drop the query string and print the path uppercase in the scheme and host (HTTPS://ID.CLOSIENT.COM/01/...) to stay in the compact alphanumeric mode.

Common mistakes

Wrong qualifier order. /01/<gtin>/21/<serial>/10/<lot> breaks the path grammar; the resolver answers 400 with "rule": "qualifier_out_of_order".
A date in the path. /01/<gtin>/17/<expiry> puts a data attribute where only qualifiers go; the resolver answers 400 with "rule": "non_qualifier_ai_in_path". Use ?17=<expiry>.
Leaving out the qualifier on a serialized item. A GTIN+serial URL (/01/<gtin>/21/<serial>) resolves to that specific item; a GTIN-only URL (/01/<gtin>) resolves to the class. Emit the qualifier when you have the data — class-level resolution can’t drive item-level experiences like recalls.
Encoding the AI itself. AI digits are path literals and must NOT be percent-encoded — only the value slot is.
Wrong link-type CURIE. linkType=gs1:pip (correct CURIE) versus linkType=pip (bare token, ambiguous) — always emit the namespaced form. Closient’s test suite normalizes both, but partner resolvers may not.
Hardcoding id.gs1.org for brand-owned products. Closient brands have their own preferred resolver host; use that so the brand owns the surface and gets the analytics.
Not URL-encoding non-ASCII or reserved characters in lot/serial. A lot of LOT-2024/Q1 becomes LOT-2024%2FQ1.

What Closient does with the URL

Once emitted, the URL can be:

Encoded as a QR code — the Print Digital Link MCP tool takes any Digital Link URL and produces a print-ready QR. For a product, lot or serial you have stored, GET /products/api/v1/products/{gtin}/barcode (and .../lots/{lot_id}/barcode, .../serials/{serial_id}/barcode) renders its barcode from the record.
Hosted by Closient’s resolver — if the URL points at id.closient.com or a *.gtin.one brand domain, Closient serves the destination (hosted page, redirect, JSON linkset, branded video, etc.) based on linkType and the brand’s resolver configuration.
Verified for serialized items — call GET /resolver/api/v1/verify/01/{gtin}/21/{serial} to confirm an item is authentic + active.

decode-gs1-ai — inverse: take a Digital Link URL apart into AIs.
resolve-gtin — once you have the URL, fetch product detail.
capture-epcis-event — emit a supply-chain event keyed on the same GTIN + serial.
closient-api-quickstart — authenticate before calling /products/api/v1/products/{gtin}/barcode or /resolver/api/v1/verify/....

Authoritative references

GS1 Digital Link Standard 1.4 — sections 4 (URI syntax), 5 (canonicalization), 6 (link types).
ISO/IEC 18975:2024 — formalization of GS1 Digital Link.
GS1 link-type vocabulary: https://www.gs1.org/voc/.
Closient API reference: https://docs.closient.com/api-reference/overview.

Getting Started

Developer Questions

User Guides

Worked Examples

Technical Guides

MCP Server

Agent Skills

Compliance

Concepts

API Reference

Resources

Build GS1 Digital Link

When to use

Anatomy of a Digital Link

Step 1 — Validate inputs

Step 2 — Compose the primary AI

Step 3 — Append qualifier AIs (canonical order)

Step 4 — Encode special characters in values

Step 5 — Attach data-attribute AIs (query string)

Step 6 — (Optional) attach `linkType` to drive resolution intent

Step 7 — Pick the host

Full example

Common mistakes

What Closient does with the URL

Authoritative references

​When to use

​Anatomy of a Digital Link

​Step 1 — Validate inputs

​Step 2 — Compose the primary AI

​Step 3 — Append qualifier AIs (canonical order)

​Step 4 — Encode special characters in values

​Step 5 — Attach data-attribute AIs (query string)

​Step 6 — (Optional) attach linkType to drive resolution intent

​Step 7 — Pick the host

​Full example

​Common mistakes

​What Closient does with the URL

​Related skills

​Authoritative references

When to use

Anatomy of a Digital Link

Step 1 — Validate inputs

Step 2 — Compose the primary AI

Step 3 — Append qualifier AIs (canonical order)

Step 4 — Encode special characters in values

Step 5 — Attach data-attribute AIs (query string)

Step 6 — (Optional) attach `linkType` to drive resolution intent

Step 7 — Pick the host

Full example

Common mistakes

What Closient does with the URL

Related skills

Authoritative references