Skip to main content

Exchange flows

Return portals typically support two different ways of handling exchanges. This page describes both patterns and explains which one TRAEDE supports today.

Two common patterns​

1. New order for the exchange​

The customer returns the original items and receives replacement items as a brand-new order. Under the hood:

  • A return is created for the items coming back.
  • When the return is received, TRAEDE issues a credit note for the returned items.
  • The exchanged items are shipped on a separate new order, which the customer either pays for (with the credit note applied) or receives at no extra cost.

This model keeps the original order immutable and produces clean audit trails: one credit note for the return, one invoice for the new order.

2. Shopify native exchanges​

Shopify's native return system supports an "exchange" outcome that swaps items on the original order without creating a new one. The replacement items appear on the original order and Shopify reconciles the difference in value internally. No separate credit note or invoice is produced.

What TRAEDE supports​

TRAEDE supports pattern 1 only. Every exchange handled by TRAEDE results in a credit note for the returned items plus a new order for the replacement items. TRAEDE does not integrate with Shopify's native exchange flow and does not rewrite an original order in response to an exchange.

See Recommended data flow for the full credit-note-based return lifecycle.

Implications for this API​

The external Return Portal API exposes the return and claim claim types only. There is no dedicated exchange claim type in this API.

Partners that want to offer exchanges to their end customers should:

  1. Call Create a return for the items coming back, using claim_type: "return".
  2. Add the replacement items to the customer's (Shopify) order themselves. TRAEDE picks the new order lines up through its regular order synchronization, which is how the revenue for the replacement items re-enters TRAEDE.
  3. Follow the normal return lifecycle through to Finalize a return. TRAEDE issues a credit note for the full value of the returned items (net of any reported fees), so the finalize call must account for the part of that credit that was settled in replacement goods rather than refunded: report the refunded amount in refund_total_price_after_vat and the exchange-settled amount in exchange_total_price_after_vat. For an even exchange no money moves at all - the refund is 0 and the exchange-settled amount equals the credit note total. See Finalizing exchanges for examples.

If the portal charges an exchange fee, report it as exchange_fee_incl_vat on the upsert. The fee is deducted from the credit note, so an even exchange with a 50.00 fee leaves a 50.00 credit note that is fully settled by the replacement goods - the customer pays the fee through the shop. See Fees.

caution

Do not attempt to send claim_type: "exchange" to this API. The exchange claim type is an internal TRAEDE concept used by the built-in return portal and is not part of the public contract.