Skip to main content
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

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.