Create Refund

Refunds one or more order items, with an optional shipping refund and an adjustment fee/refund. The same eligibility checks as the admin Refund screen apply (the order must not be closed or marked fraud, and each item's requested quantity must be ≤ its still-refundable quantity, qty_to_refund). The refund totals are computed from the items + shipping + adjustments, and the total cannot exceed the order's remaining refundable balance.

Endpoint

Endpoint	Method
/api/admin/orders/{orderId}/refunds	POST

Request body

Field	Type	Required	Notes
items	array of { orderItemId, quantity }	yes	Items to refund.
shipping	float	no (default 0)	Original shipping to refund (base currency).
adjustmentRefund	float	no (default 0)	Positive adjustment added to the refund total.
adjustmentFee	float	no (default 0)	Fee subtracted from the refund total.

Errors

HTTP	Lang key	Message
422	bagistoapi::app.admin.order.actions.refund.closed	Closed orders cannot be refunded.
422	bagistoapi::app.admin.order.actions.refund.fraud	Fraud orders cannot be refunded.
422	bagistoapi::app.admin.order.actions.refund.nothing-to-refund	There is nothing left to refund on this order.
422	bagistoapi::app.admin.order.actions.refund.no-permission	You do not have permission to create refunds.
422	bagistoapi::app.admin.order.actions.refund.qty-exceeds	Requested quantity (:requested) exceeds available quantity (:available) for SKU :sku.
422	bagistoapi::app.admin.order.actions.refund.amount-zero	The computed refund amount is zero. Adjust quantity, shipping or adjustment values.
422	bagistoapi::app.admin.order.actions.refund.amount-exceeds-max	The refund amount (:amount) exceeds the maximum refundable amount (:max).
422	bagistoapi::app.admin.order.actions.refund.failed	Could not create the refund.

To check the computed totals before committing, call Refund Preview (POST /api/admin/orders/{orderId}/refunds/preview) — it runs the same calculation without saving anything.