Returns

All endpoints in this section take an external return portal's publicId as a path parameter. The portal must belong to the authenticated brand and its type must not be traede. Any error returned by these endpoints follows our standard error format.

Upsert a return

Endpoint: PUT /v10/external-return-portals/{publicId}/returns

Creates a new return, or updates an existing one in place. The return is identified by the (publicId, rma) pair: TRAEDE looks for an existing return on the same portal with the same rma. If none is found the call creates a new return in approved status; if one is found the call merges the incoming payload into it.

The endpoint is idempotent: replaying the same body against the same (publicId, rma) leaves the return in the same state. Because this single PUT serves both creation and updates, external portals do not need to track TRAEDE's numeric return.id to mutate a return - the external rma is enough.

caution

This endpoint rejects calls against a traede-type portal. Use an external portal (reversio, returnflows, float or custom).

Request parameters

Parameter	Data type	Required	Default	Description
email	string	Yes for a new return; optional thereafter		The customer email on the original order. Used to authenticate the return against the order. When provided on an existing return it must match the bound order's delivery email.
order_number	string	Yes for a new return; optional thereafter		The order number of the original order. When provided on an existing return it must match the bound order's order_number.
return	object	Yes		Return data.

Return data

Parameter	Data type	Required	Default	Description
rma	string	Yes		The RMA identifier from the external portal. Stored on the TRAEDE return and must contain at least one digit - the digits are used to derive TRAEDE's internal rma_number. Unique per portal.
notes	string			Free-text notes on the return.
status	string			Update the return status. Valid transitions are constrained by the normal return state machine.
return_fee_incl_vat	float			The return fee charged to the customer, including VAT. Deducted from the credit note when the return is received - see Fees.
exchange_fee_incl_vat	float			The exchange fee charged to the customer, including VAT. Deducted from the credit note when the return is received - see Fees.
labelless_code	string			A labelless / dropoff code the customer can present at the carrier. The external portal is responsible for booking the return label and reports the code here so TRAEDE can surface it to the customer.
track_trace	string			The tracking number for the return shipment booked by the external portal.
track_trace_link	string			A URL the customer can use to track the return shipment.
shopify_refund_gift_card	boolean		false	If true, the refund will be issued as a Shopify gift card.
shopify_refund_gift_card_bonus_type	string			The type of bonus applied to the gift card refund. Possible values: percentage, fixed.
shopify_refund_gift_card_bonus_value	float			The bonus value to apply, in the units implied by shopify_refund_gift_card_bonus_type.
shopify_refund_gift_card_free_shipping	boolean		false	If true, the customer is refunded for shipping in addition to the line amounts.
lines.*		Yes		An array of at least one return line data. lines represents the desired full set of lines on the return; see Line merge behavior.

Fees

return_fee_incl_vat and exchange_fee_incl_vat are deducted from the credit: when the return is received, TRAEDE issues the credit note net of the fees (the fee amount is carried as a handling fee on the credit note). A returned item of 100.00 with a 25.00 return fee produces a credit note of 75.00, and the finalize call must account for 75.00.

caution

Do not also add fees reported here as line items on the (Shopify) order - the fee would then be counted twice: once as order revenue and once as a reduction of the credit note.

Return line data

Each line identifies a variant on the original order. Provide variant_id, sku or ean - whichever is most convenient.

Parameter	Data type	Required	Default	Description
variant_id	int	Yes, if no sku or ean is given		The TRAEDE variant ID.
sku	string	Yes, if no variant_id or ean is given		The variant SKU. Must match exactly one variant on the brand.
ean	string	Yes, if no variant_id or sku is given		The variant EAN. Must match exactly one variant on the brand.
quantity	int	Yes		The quantity being returned. Must be greater than zero.
claim_type	string	Yes		Possible values: return, claim.
claim_cause_id	int	Yes, if portal requires claim causes and no claim_cause_code is given		ID of a claim cause configured on the brand. Must belong to the authenticated brand.
claim_cause_code	string	Yes, if portal requires claim causes and no claim_cause_id is given		The code of a claim cause configured on the brand. Looked up case-insensitively; if multiple claim causes share the same code the request is rejected.
unit_price_incl_vat	float	Yes		The unit price including VAT that the customer paid on the original order. Used for refund math.
text	string			A comment from the customer about this line, stored as the line's comments.
regulate_inventory	boolean		true	If false, inventory will not be adjusted when the return is received. Typically left at default.

Line merge behavior

lines always represents the full desired set of lines on the return. When the PUT targets an existing return, TRAEDE keeps existing line IDs where possible so that any data attached to a line (e.g. uploaded photos) is preserved across updates. Each incoming line is matched against the return's existing lines in this order:

1. Exact natural key - same variant_id, claim_type, claim_cause_id, text and unit_price_incl_vat. This is the happy path: an unchanged line keeps the same id.
2. Same variant - same variant_id, regardless of the other fields. An existing line for the variant is re-used and its fields updated in place.
3. New line - if no existing line can be claimed, a new line is created.

After every input line has been processed, any existing lines that were not claimed by an input line are deleted from the return.

Each existing line is claimed by at most one input line. An input line picks the first unclaimed existing line that matches at the current cascade level.

Response

On success the endpoint returns HTTP 201 when a new return was created and HTTP 200 when an existing one was updated. The body is an object with two keys:

Parameter	Data type	Description
return	object	The resulting return in TRAEDE. See Response return object.
created	boolean	true if this PUT created a new return, false if it merged into an existing one.

Response return object

Parameter	Data type	Description
id	int	TRAEDE's internal numeric return ID.
rma	string	The external RMA identifier you sent in.
rma_number	int	The numeric part of the RMA, derived from the digits in rma.
return_status	string	One of approved, received, credited.
source	string	The portal type that owns this return (e.g. custom, reversio).
notes	string | null	Free-text notes on the return.
return_fee_incl_vat	float | null	The return fee including VAT, echoed back from the request.
exchange_fee_incl_vat	float | null	The exchange fee including VAT, echoed back from the request.
labelless_code	string | null	Labelless / dropoff code for the return shipment, as reported by the portal.
track_trace	string | null	Tracking number for the return shipment, as reported by the portal.
track_trace_link	string | null	Public tracking URL for the return shipment, as reported by the portal.
shopify_refund_gift_card	boolean	Whether the refund is issued as a Shopify gift card.
shopify_refund_gift_card_bonus_type	string | null	percentage, fixed or null.
shopify_refund_gift_card_bonus_value	float | null	The bonus value, in the units implied by the bonus type.
shopify_refund_gift_card_free_shipping	boolean	Whether the refund includes shipping.
total_price_after_vat	float | null	Total refunded amount including VAT.
lines[]	array	One entry per line on the return. See Response return line.

Response return line

Parameter	Data type	Description
id	int	TRAEDE's internal line ID. Stable across updates where possible.
variant_id	int	The TRAEDE variant ID.
quantity	int	Same value as expected_return, for symmetry with the request shape.
expected_return	int	The quantity the customer said they would return.
returned	int | null	The quantity the warehouse has actually received so far.
claim_type	string	return or claim.
claim_cause_id	int | null	The resolved claim cause ID.
net_price	float	The unit price excluding VAT, computed from unit_price_incl_vat.
unit_price_incl_vat	float	The unit price including VAT, echoed back from the request.
text	string | null	The customer comment on the line.
regulate_inventory	boolean	Whether inventory will be adjusted when the line is received.

Request example

PUT /v10/external-return-portals/abc123xyz/returns

{
  "email": "jane@example.com",
  "order_number": "1001",
  "return": {
    "rma": "RMA-1001",
    "return_fee_incl_vat": 5.0,
    "labelless_code": "LL-ABC-123",
    "track_trace": "JD000123456789",
    "track_trace_link": "https://tracking.example.com/JD000123456789",
    "lines": [
      {
        "sku": "1000-Black-S",
        "quantity": 1,
        "claim_type": "return",
        "claim_cause_code": "too-small",
        "unit_price_incl_vat": 125.0,
        "text": "Does not fit"
      }
    ]
  }
}

Response example

{
  "return": {
    "id": 987,
    "rma": "RMA-1001",
    "rma_number": 1001,
    "return_status": "approved",
    "source": "custom",
    "notes": null,
    "return_fee_incl_vat": 5.0,
    "exchange_fee_incl_vat": 0.0,
    "labelless_code": "LL-ABC-123",
    "track_trace": "JD000123456789",
    "track_trace_link": "https://tracking.example.com/JD000123456789",
    "shopify_refund_gift_card": false,
    "shopify_refund_gift_card_bonus_type": null,
    "shopify_refund_gift_card_bonus_value": null,
    "shopify_refund_gift_card_free_shipping": false,
    "total_price_after_vat": 125.0,
    "lines": [
      {
        "id": 4321,
        "variant_id": 5555,
        "quantity": 1,
        "expected_return": 1,
        "returned": null,
        "claim_type": "return",
        "claim_cause_id": 42,
        "net_price": 100.0,
        "unit_price_incl_vat": 125.0,
        "text": "Does not fit",
        "regulate_inventory": true
      }
    ]
  },
  "created": true
}

Finalize a return

Endpoint: POST /v10/external-return-portals/{publicId}/returns/finalize

Books all OPEN credit notes on the return, which transitions the return to credited. Call this once the external portal has settled the return with the customer - by issuing a refund in the customer's payment provider, by giving replacement goods in an exchange, or a combination of both. The return is identified by its external rma in the request body.

caution

Preconditions:

• The return must be in received or credited status. Otherwise the request is rejected with a validation error.
• The return must have at least one credit note.
• The sum of refund_total_price_after_vat and exchange_total_price_after_vat must match the total credited amount across the return's credit notes, with a tolerance of ±0.01. Otherwise the request is rejected with a validation error showing the amounts.

Both amounts are reported as positive numbers. A return of 120.00 that was fully refunded is finalized with "refund_total_price_after_vat": 120.0.

The credit note total is net of fees reported on the upsert (see Fees): a returned item of 100.00 with a 25.00 return fee produces a credit note of 75.00, so the finalize amounts must sum to 75.00.

Parameter	Data type	Required	Default	Description
rma	string	Yes		The external RMA identifier of the return to finalize. Must match the rma used when upserting.
refund_total_price_after_vat	float	Yes		The refunded amount the portal has issued to the customer, as a positive number. Compared against TRAEDE's credit notes together with exchange_total_price_after_vat.
exchange_total_price_after_vat	float		0	The part of the credit that was settled in replacement goods instead of a refund, as a positive number. Cannot exceed the credit note total.

Finalizing exchanges

When the customer exchanges an item, the portal adds the replacement goods to the (Shopify) order itself and little or no money is refunded - yet TRAEDE still issues a credit note for the full value of the returned item. In that case the portal must account for the full credit note across both channels:

refund_total_price_after_vat (refunded) + exchange_total_price_after_vat (settled in replacement goods) = credit note total

Examples for a returned item bought at 100.00:

Scenario	Credit note total	refund_total_price_after_vat	exchange_total_price_after_vat
Pure return, full refund	100.0	100.0	0 (or omitted)
Pure return with a 25.00 return fee withheld	75.0	75.0	0 (or omitted)
Even exchange (replacement worth 100.00)	100.0	0	100.0
Even exchange with a 50.00 exchange fee (customer pays the fee in the shop)	50.0	0	50.0
Exchange to a cheaper item (80.00), 20.00 refunded	100.0	20.0	80.0
Exchange to a pricier item (customer pays the difference in the shop)	100.0	0	100.0

Data of response

Parameter	Data type	Required	Default	Description
success	boolean	Yes		Always true when the request succeeds.
return_id	int	Yes		The TRAEDE ID of the return that was booked.
rma	string	Yes		The RMA string as stored on the return.

Request example

POST /v10/external-return-portals/abc123xyz/returns/finalize

{
  "rma": "RMA-1001",
  "refund_total_price_after_vat": 120.0
}

Request example (even exchange, no refund)

POST /v10/external-return-portals/abc123xyz/returns/finalize

{
  "rma": "RMA-1002",
  "refund_total_price_after_vat": 0,
  "exchange_total_price_after_vat": 120.0
}

Response example

{
  "success": true,
  "return_id": 987,
  "rma": "RMA-1001"
}