Returns & Claims

Returns and claims are created by staff on the order detail page at /dashboard/platform/orders/[id]. Customers cannot start either from the storefront.

Returns

A Return links to an order and has status (requested, received, requires_action, canceled), refundAmount, receivedAt, shippingData, idempotencyKey, noNotification and metadata. Each ReturnItem links an order line with quantity, requestedQuantity, receivedQuantity, a ReturnReason and a note. Creating returns requires canManageReturns.

The Returns section on the order page can:

• create a return in requested status with items and reasons;
• change the return status;
• refund it with processReturnRefund(returnId, paymentId, idempotencyKey).

processReturnRefund requires both canManageReturns and canManagePayments. It needs a positive refundAmount and a payment that belongs to the order. It refuses refunds that would exceed the captured amount and refuses manual-tender payments. It calls the provider's refund operation and records a Refund. A retry with the same key returns the first result.

• Marking a return received does not put stock back. Nothing in the return flow changes inventoryQuantity or writes a stock movement.
• Return shipping labels are not generated from the return.
• Manual-tender orders cannot be refunded through this path.

Claims

A ClaimOrder has type (refund or replace), paymentStatus (na, not_refunded, refunded), fulfillmentStatus, refundAmount, canceledAt and links to the order, claim items, fulfillments, line items, a return and shipping methods. A ClaimItem has a reason, quantity, note, the line item and variant, plus ClaimImage and ClaimTag records. Creating claims requires canManageOrders.

The Claims section on the order page creates a claim and its items, and updates the claim's payment and fulfillment status. /dashboard/platform/claims lists claims and their status.

• Changing a claim's status does not move money or goods. No refund is issued and no replacement order is created.
• Claim items are created one by one after the claim. If one fails, the claim is left with some items.
• ClaimImage records are created from image URLs. There is no upload step in the claim form.

Swaps

A Swap model exists with payment and fulfillment status fields. No dashboard screen or mutation creates or processes swaps.