Skip to main content

Create Return Receipt from RMA

POST 
/api/rmas/:rma/receipts

Record a return receipt against an RMA (items physically received at the warehouse).

Required scope: returns:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token.

Action values: added_to_stock, discarded, new_blemished_sku

  • For new_blemished_sku: provide blemished_configurations array with sku, condition, and reference fields
  • product_id: the product being received back (can differ from original if substituted)
  • original_product_id: the original product (if product_id differs)

Lot / batch capture (optional per line - only meaningful for added_to_stock on lot-tracked products):

  • lots[]: { batch_number, manufacture_date, expiry_date, quantity, lot_notes }. Each lot becomes its own FIFO layer; the lot quantities must sum to the line quantity.
  • Batch number + expiry date are REQUIRED on each lot only when the return is traceable to its original sale (the RMA is linked to a sales order). For a blind/untraceable RMA (no sales order link), a blank batch is auto-generated (AUTO-...) at persistence and an undated lot is valid - the receiver is never forced to invent a lot id.

Requires permission: returns.receive rma_line_id is OPTIONAL — omit it (supply product_id) to receive an item NOT on the RMA; it is stored and flagged unexpected_item=true rather than dropped.

Serials. Serials can be sent on every received quantity type (new, blemished or discarded). A serial SKU.io never recorded is added with the chosen disposition under Log and allow mismatch, or refused with 422 under Require exact match. Deleting the receipt puts each serial back the way it was before the return.

A line that names only rma_line_id is checked against that RMA line's product, so a lot-tracked product still needs its lot details.

Request​

Responses​

Created

Response Headers
    Content-Type