> ## 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.

# Manage Lot Templates

> List, create, read, update, preview and archive an organization's lot and serial number templates — the token formats its lot generator mints identifiers from — the programmatic equivalent of the dashboard's Lot templates pages.

Programmatic equivalent of the dashboard's `lots/templates/` pages (the list,
the new-template form and the edit form). A lot template is a token format
(for example `LOT-{YYYY}{JJJ}-{####}`) plus the counter rules the lot
generator mints lot or serial identifiers from. The identifiers end up printed
on physical goods, so every change matters.

## When to use

* A brand owner wants a new lot or serial number format, or wants to fix or
  rename an existing one.
* A brand owner wants to see sample identifiers a format would produce before
  committing to it.
* A template is retired and should stop generating runs.

## Auth

`X-API-Key` header or OAuth token. Every endpoint here, reads included, needs
an OWNER or MANAGER of the organization (or an API key with the MANAGER role or
above): an EDITOR or VIEWER key gets `403`.

## Flow

```
GET   /products/api/v1/lots/templates/
POST  /products/api/v1/lots/templates/
GET   /products/api/v1/lots/templates/{template_id}/
PATCH /products/api/v1/lots/templates/{template_id}/
POST  /products/api/v1/lots/templates/{template_id}/preview/
POST  /products/api/v1/lots/templates/{template_id}/archive/
GET   /products/api/v1/lots/templates/{template_id}/versions/
```

The organization is the API key's organization. Ids from another organization
are `404`.

* **`GET` list** — the organization's templates, newest-modified first.
  Filter with `target_field` (`lot` or `serial`) and `is_archived` (omit it for
  non-archived templates only).
* **`POST` create** — body with `name` and `format_string` (required),
  `target_field` (`lot` default, or `serial`), `description`, `character_set`
  (`GS1_AI82` default), `check_digit_algorithm` (`none`, `mod10`,
  `iso7064_11_2`), `reset_condition` (`never`, `daily`, `weekly`, `monthly`,
  `on_count_reached` with `reset_threshold`), `scope_kind` (`global`,
  `per_product`, `per_product_per_date_bucket`), `starting_value` and
  `max_collision_retries`. The format is validated against the target field; a
  bad one is `422`.
* **`PATCH`** — any of the create fields except `target_field`; a field left
  out, or sent as `null`, keeps its value. A format-affecting change
  (`format_string`, `character_set`, `check_digit_algorithm`) on a template
  that has already generated runs **bumps its version** and carries the counter
  forward; earlier runs stay pinned to the version they used.
* **`POST preview`** — body `{"count": 5}`: renders sample identifiers from the
  starting value without storing anything or advancing the counter.
* **`POST archive`** — the template stops generating runs. It is kept, with
  its runs and versions.
* **`GET versions`** — every version that has runs, plus the current one,
  with each version's run count.

There is no API for cloning a template or deleting one; those stay on the
dashboard.

## Verify

1. `GET` the list (with `is_archived=true` for an archive) and confirm each
   template you touched has the name, format, target and archived state you
   intended, and that no other template changed.
2. `POST preview` on each template you created or reformatted, and show the
   sample identifiers to your human before anything is generated from it.
3. After a `PATCH` to a template with runs, `GET versions` shows the new
   version as current and the old one with its runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.