Add an order item to a package
Adds an order line item (or partial quantity) to a package. Either order_item_id OR
product_id must be supplied; if both are provided the order_item_id is authoritative.
Two invariants enforced BEFORE the INSERT (canonical writer
utils/fulfillment-helpers.mjs::addItemToPackage):
- Item-on-order — the product must be on the parent order. Returns 422
product_not_on_orderwith envelope{error, code, type:'validation_error', param:'product_id', hint, product_id, order_id}when the product is not on any order_items row for the order. - Quantity cap — the requested quantity must not exceed
SUM(ordered_qty) - SUM(elsewhere_packed)across ALL packages of the order for this product. Returns 422package_quantity_exceeds_orderedwith envelope{error, code, type:'validation_error', param:'quantity', hint, ordered_qty, already_packed_qty, remaining_qty, product_id}.
Multi-line same-product orders: the first non-fully-packed line wins. Both refusal paths write to the parent order activity log.
Requires fulfillment:write scope.
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Headers
Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.
255Path Parameters
Body
Response
Package item added
A line item placed inside a package (one order_item can be split across packages).

