> ## 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 Product Lots

> Register, list, update, and delete a product's production lots (GS1 batch/lot numbers) -- the programmatic equivalent of the dashboard's product lots page.

Programmatic equivalent of the dashboard's `products/<gtin>/lots/` page.

## When to use

* A brand owner wants each production lot (GS1 AI 10) of a product on record, with its
  dates and quantity, so scans and traceability events can name it.
* A lot's expiration date, best-before date or quantity needs correcting.
* A lot was registered by mistake and needs removing.

## Auth

`X-API-Key` header or OAuth token. The caller must be a member of the product's
organization with the contribute role (Owner, Manager or Editor). A read-only key is
refused with `403`; a product or lot another organization owns answers `404`, so the API
never confirms it exists.

## Flow

```
GET    /products/api/v1/products/{gtin}/lots
POST   /products/api/v1/products/{gtin}/lots
GET    /products/api/v1/products/{gtin}/lots/{lot_id}
PATCH  /products/api/v1/products/{gtin}/lots/{lot_id}
DELETE /products/api/v1/products/{gtin}/lots/{lot_id}
POST   /products/api/v1/products/{gtin}/lots/register-observed
```

* **List** -- every lot on the product, paginated.
* **Create** -- the body carries `lot_identifier` (1 to 20 printable ASCII characters, no
  spaces) and optionally `production_date`, `expiration_date`, `best_before_date`,
  `quantity` and `unit_of_measure`; fields are listed in the OpenAPI document at
  `/products/api/v1/openapi.json`.
* **Update** -- `PATCH` only the fields to change; an explicit `null` clears a date or the
  quantity. The identifier is locked once a traceability event references the lot.
* **Delete** -- removes the lot and the serials registered under it permanently.
* **Register observed** -- records a lot identifier a scan was seen carrying; repeating it
  is harmless.
* **Read back** -- every write returns the saved lot; list again to confirm.

## Errors

`403` for a read-only key, or when the free plan's lot allowance is used up (the body
carries an `upgrade_url`); `404` for a product or lot the caller cannot see; `409` for a
lot identifier the product already has; `422` for an invalid value or an empty update.

## Notes

The fields a brand writes on a lot are defined once on the model
(`ProductLot.BRAND_EDITABLE_FIELDS`); the dashboard form and the API schemas are pinned to
that set. Recalls are not part of this skill.


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