How do I set or clear a purchase order line's lot via the External API?

Last updated: September 1, 2026

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)

Cause

Fix

No lot identifier and no clear_lot

Send exactly one of lot_id, lot_number, or clear_lot: true

Both lot_id and lot_number in the same request

Send only one

clear_lot combined with a lot identifier

These are mutually exclusive

Lot belongs to a different product

Lots are SKU-scoped; check you have the right lot

lot_number matched no lot and create_lot was not set

Add "create_lot": true or use lot_id

lot_number matched more than one lot

Use lot_id instead

The SKU does not have lot tracking enabled

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


Related