Skip to main content

Issue Channel Refund

POST 
/api/sales-orders/:salesOrder/channel-refunds

Creates and submits a refund to the order's sales channel. Amounts are validated server-side against the channel's refundable state: line quantities may not exceed the refundable quantity, line amounts may not exceed quantity times unit price, and the shipping amount may not exceed the refundable shipping. Line tax is added automatically to the total sent to the channel.

Fields:

  • lines (array, required, may be empty when only shipping or a custom amount is refunded)
  • lines[].sales_order_line_id (integer, required) — must belong to the order
  • lines[].quantity (number, required, min 0)
  • lines[].amount (number, required, min 0) — product amount excluding tax
  • lines[].restock (string, optional: return | cancel | no_restock) — channels with restock support only
  • lines[].restock_location_id (string, optional) — channel location for restocking
  • shipping_amount (number, optional, min 0)
  • custom_amount (number, optional, min 0) — only on channels whose capabilities report custom_amount: true
  • reason (string, optional; required when capabilities report reason_required: true — use a value from capabilities.reasons)
  • note (string, optional, max 1000)
  • notify_customer (boolean, optional)

Only one refund request may be in flight per order at a time; a second submission returns 409 until the first reaches a terminal state.

Asynchronous channels (eBay) return status: awaiting_channel; the status updates automatically once the channel finishes processing.

Requires a Bearer token and refund permission.

  • Each lines[].sales_order_line_id must be unique within the request (distinct validation) — duplicate entries are rejected with a 422 because their summed quantity could exceed the line's refundable quantity.

Request​

Responses​

Created

Response Headers
    Content-Type