The request body is a flat array of package objects — not wrapped in a parent object. The purchase order must be in IN_PROGRESS status.

With the Order Approval module, an order in AWAITING_APPROVAL or REJECTED status is accepted too; see Order approval below.

quantity and to_par

Each package entry must provide either quantity or to_par, but not both:

• quantity — the number of units to order. Must be a non-negative number. Sending 0 removes the package from the order if it was already present.
• to_par — when true, the quantity is automatically calculated as par − (current stock + outstanding orders), rounded up. If stock already meets or exceeds par, the calculated quantity is 0 and the package is removed from the order if it was already present.

Order approval

With the Order Approval module, an order can also be in AWAITING_APPROVAL or REJECTED status. Adding packages to such an order takes it back first, in the same transaction as the edit, so a refused edit leaves it as it was:

• The order returns to IN_PROGRESS and becomes the caller's, whoever owned it before.
• Its pending order approval is cancelled (status: cancelled). A rejected one stays rejected. If the order still needs approval when it is sent again, a new order approval is created.
• The caller's own IN_PROGRESS order for the same outlet and supplier is deleted, without warning, because a user can have only one open order per outlet and supplier. The caller's orders in AWAITING_APPROVAL are not affected.

This works whether or not the library still has the Order Approval module, so orders parked before the module was removed can still be edited and sent.