How do I correct a receiving-report line quantity via the External API?

Correcting a receiving-report line quantity — External API

Luminous lets you preview and apply a quantity correction on a posted receiving-report line directly from the External V1 API. This mirrors the correction tool in the admin interface.

Endpoint

POST /external/api/v1/receiving-reports/items/{receivingReportItemId}/correct-quantity

Request body

Field	Type	Required	Description
`correct_qty`	number	Yes	The correct quantity in the same unit as the original received quantity. Not a delta — the absolute right number.
`preview`	boolean	No	`true` to measure the impact without posting. Defaults to `false` (apply).
`reason`	string	No	Free-text reason recorded on the adjustment.
`confirm_shelf_only`	boolean	No	Required `true` when correcting upward (increase); an increase posts a shelf-count adjustment and does not advance purchase-order pegs or fulfillment-order releases.
`unit_cost`	number	No	Override cost per unit on the adjustment entry.

Preview first (recommended)

Always preview before applying:

{
  "correct_qty": 30,
  "preview": true
}

Response includes:

direction — "increase" or "decrease"
delta — signed quantity change (e.g. -10 when reducing from 40 to 30)
Any fulfillment-order over-release warnings

Apply the correction

Re-send the same body with preview omitted or false. The system posts an inventory adjustment linked to the receiving report and recalculates on-hand stock.

Important constraints

Only posted (received) lines can be corrected.
Decreases adjust on-hand and may flag over-released fulfillment orders for review.
Increases require confirm_shelf_only: true and do not advance PO pegs or FO releases — prefer creating a second receiving report when quantity was genuinely under-received on the PO.
The endpoint respects accounting-period locks; a correction into a closed period returns an error.

Idempotency

This endpoint does not carry the idempotency key middleware. If you need to guard against duplicate retries, check the current received quantity (via GET /receiving-reports/{id}) before posting a correction.