> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GS1 Digital Link Resolution

> Resolve GTINs to structured product data using configurable resolution rules.

The Closient Resolver implements the [GS1 Digital Link](https://www.gs1.org/standards/digital-link) standard, enabling any GTIN to be resolved to structured product data via a standard URI format. Resolution behavior is configurable through rules that support time-based routing, scope hierarchy, and custom destinations.

## URI Format

A GS1 Digital Link URI encodes a primary identifier and optional qualifiers as path segments:

```
https://www.closient.com/01/{gtin}
https://www.closient.com/01/{gtin}/10/{lot}/21/{serial}
```

### Supported Application Identifiers

| AI    | Name           | Example              | Description                |
| ----- | -------------- | -------------------- | -------------------------- |
| `01`  | GTIN           | `00012345678905`     | Primary product identifier |
| `00`  | SSCC           | `123456789012345678` | Shipping container code    |
| `10`  | Batch/Lot      | `ABC123`             | Production batch           |
| `21`  | Serial         | `SN001`              | Individual item serial     |
| `17`  | Expiry         | `261231`             | Expiry date (YYMMDD)       |
| `414` | GLN (Party)    | `1234567890123`      | Party identifier           |
| `417` | GLN (Location) | `1234567890123`      | Location identifier        |

## Content Negotiation

The resolver returns different formats based on the `Accept` header:

| Accept Header              | Response                                  |
| -------------------------- | ----------------------------------------- |
| `application/json`         | JSON product data (default)               |
| `application/linkset+json` | GS1 Linkset JSON                          |
| `text/html`                | HTML redirect to product information page |

## Resolution Rules

Resolution behavior is controlled through rules configured per organization. Rules determine where a Digital Link request is routed.

### Scope Hierarchy

Rules are evaluated from most specific to least specific scope. The first matching rule wins:

| Priority    | Scope            | Matches                                 |
| ----------- | ---------------- | --------------------------------------- |
| 1 (highest) | **Serial**       | Specific serial number within a product |
| 2           | **Batch**        | Specific batch/lot within a product     |
| 3           | **Product**      | A specific GTIN                         |
| 4           | **Brand**        | All products under a brand              |
| 5 (lowest)  | **Organization** | All products in the organization        |

Within each scope, rules are ordered by `order_index` (lower = higher priority).

### Destination Types

| Type          | Behavior                                             |
| ------------- | ---------------------------------------------------- |
| `HOSTED_PAGE` | Redirect to Closient-hosted product information page |
| `CUSTOM_URL`  | Redirect to your own URL                             |

For custom URLs, configure fallback behavior when the URL is unreachable:

* **Skip rule** — evaluate the next rule in priority order
* **Fallback to hosted** — use the Closient hosted page instead

Custom URL health is monitored automatically with consecutive failure tracking.

### Time-Based Routing

Rules support time criteria for conditional routing (all criteria are AND-ed when present):

| Criteria        | Format                     | Example                          |
| --------------- | -------------------------- | -------------------------------- |
| Absolute window | UTC datetimes              | 2026-01-01 to 2026-12-31         |
| Annual window   | MM-DD (supports year wrap) | 11-01 to 02-28 (holiday season)  |
| Day of week     | 0=Monday through 6=Sunday  | \[0, 1, 2, 3, 4] (weekdays only) |
| Time of day     | HH:MM                      | 09:00 to 17:00                   |

Time criteria use the organization's configured routing timezone (IANA format, e.g., `America/New_York`).

### Link Types

Rules can be scoped to specific GS1 link types:

| Link Type                | Description                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `gs1:pip`                | Product information page                                                                             |
| `gs1:certificationInfo`  | Certifications and compliance                                                                        |
| `gs1:sustainabilityInfo` | Sustainability data                                                                                  |
| `gs1:recipeInfo`         | Ingredients and recipes                                                                              |
| `gs1:ingredientsInfo`    | Ingredient disclosure (e.g., [US state disclosure laws](/compliance/us-state-ingredient-disclosure)) |
| `gs1:safetyInfo`         | Safety / warning information (paired with `gs1:ingredientsInfo` for LA SB 14)                        |
| `gs1:traceability`       | Supply chain traceability                                                                            |

## GS1 Conformance

The Closient Resolver is designed to conform to the GS1 Digital Link standard, including proper handling of `Accept` headers, `Link` response headers, and linkset JSON format. A built-in conformance test suite is available for validation.

See the [Resolver API reference](/api-reference/resolver) for full endpoint documentation.