Skip to main content

Capture Damaged Unit

POST 

/api/return-receipts/quick-damage-capture

Record a damaged unit in one step: create (or reuse) the blemished SKU for the product, record the financial loss, and optionally issue a cash credit.

Required scope: returns:write

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

Authentication: Requires Bearer token. Permission: returns.receive. Token scope: returns:write.

damage_source decides what happens to stock:

  • customer_return (default): the unit comes back from a customer, so a return receipt adds it to the blemished SKU. May be linked to a sales order / line and may issue a cash credit. When blind receiving is off, a return must be linked to a sales order.
  • existing_stock: on-hand stock damaged in store. The unit is moved from the original SKU to the blemished SKU (a decrease adjustment on the original and an increase on the blemished SKU, at the original's FIFO cost), so total units and value are unchanged. No return receipt, RMA or credit is created; sales_order_id, sales_order_line_id and issue_cash_credit=true are rejected.

Fields:

  • damage_source (optional): customer_return | existing_stock
  • product_id (required): product that was damaged
  • warehouse_id (required): warehouse holding the unit
  • quantity (required): units damaged, min 1
  • damage_description (required): max 500 chars
  • blemished_sku (optional): SKU for the blemished product; defaults to the original SKU with a -DMG suffix
  • sales_order_id, sales_order_line_id (optional, customer_return only)
  • return_reason_id (optional)
  • issue_cash_credit (optional, customer_return only)
  • credit_amount_per_unit (required when issue_cash_credit is true), min 0
  • customer_id (required when issuing a credit without a sales order)
  • notes (optional): max 1000 chars
  • claim_from_vendor (optional, boolean): also raise a DRAFT vendor credit (a damage claim, reason goods_damaged) against the product's supplier so the cost is recovered. Requires permission purchase_orders.update (403 without it). Works with both damage sources.
  • vendor_claim_supplier_id (optional): supplier to claim from; defaults to the product's default supplier. 422 when the product has no supplier and none is given.
  • vendor_claim_unit_cost (optional): per-unit claim amount, min 0; defaults to the supplier's cost, then the units' book cost.
  • vendor_claim_reference (optional): the vendor's RA / claim number, saved as the credit's supplier reference.

Response: damage_source, blemished_product_id, blemished_sku, quantity_damaged, financial_loss, plus return_receipt_id / return_receipt_line_id / rma_id / sales_credit_id for a customer return, or original_adjustment_id / blemished_adjustment_id for shelf damage (the other set is null). With claim_from_vendor: vendor_credit_id, vendor_credit_number, vendor_claim_supplier_id, vendor_claim_supplier_name, vendor_claim_amount (all null otherwise). The claim's single line targets the blemished SKU with the write_off_goods behaviour, so authorising it writes the damaged units off once; its metadata.source is quick_damage_capture and links back to the capture records.

Request​

Responses​

OK

Response Headers
    Content-Type