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

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