Setting a PO line's lot via the External API

The External V1 API has a dedicated endpoint to assign, change, or unassign the lot on one purchase order line. It touches only the lot field — no quantities, costs, or inventory transactions are affected, so it is safe to call repeatedly on an active order.

PATCH /external/api/v1/purchase-orders/{purchase_order_id}/items/{line_item_id}/lot

Authentication: Authorization: Bearer <api_token>

Assigning a lot by ID

If you already know the lot's ID in Luminous:

{ "lot_id": 5512 }

Assigning a lot by number

If you know the lot number (a string):

{ "lot_number": "ACME-2026-08-A" }

lot_name is accepted as an alias for lot_number.

Creating a lot that does not exist yet

Add "create_lot": true to have Luminous create the lot when the number does not match any existing one for that SKU. Optional date and code fields are used only on creation:

{
  "lot_number": "ACME-2026-NEW",
  "create_lot": true,
  "production_date": "2026-07-01",
  "expiry_date": "2027-07-01",
  "manufacturer_code": "ACME"
}

Unassigning (clearing) a lot

Send clear_lot: true to remove the lot from the line:

{ "clear_lot": true }

⚠️ Unassigning requires clear_lot: true explicitly. Sending an empty string, null, or omitting the lot fields entirely is rejected with a 422 and leaves the existing lot untouched. This is intentional: an absent value means "nothing to say", not "please delete the lot". Automation templates with unset variables will not accidentally clear a lot that was already set.

Successful response

{
  "data": {
    "id": 18244,
    "purchase_order_id": 4471,
    "product_id": 903,
    "lot_id": 5512,
    "lot_number": "ACME-2026-08-A"
  }
}

After clearing, lot_id and lot_number are both null.

Validation errors (422)

CauseFix
No lot identifier and no clear_lotSend exactly one of lot_id, lot_number, or clear_lot: true
Both lot_id and lot_number in the same requestSend only one
clear_lot combined with a lot identifierThese are mutually exclusive
Lot belongs to a different productLots are SKU-scoped; check you have the right lot
lot_number matched no lot and create_lot was not setAdd "create_lot": true or use lot_id
lot_number matched more than one lotUse lot_id instead
The SKU does not have lot tracking enabledEnable lot tracking on the product first

What happens in the receiving form

A lot recorded on a PO line before goods arrive is offered as the default in the receiving form when the warehouse team opens a receipt against that PO. The receiver can accept or change it — it is a starting point, not a lock.