Concepts of the Return Portal API

Where the external portal fits

TRAEDE ships with its own built-in return portal, which is sufficient for most brands. When a brand wants a different customer experience - for example a marketplace-style return portal or a portal built by one of our partners - they instead use an external return portal. TRAEDE still stores the returns, updates inventory and issues credit notes; the external portal drives the customer journey and issues the refund.

In TRAEDE, an external return portal is just a return portal with a non-default type. Brands configure one or more of them in their account and share the public_id and webhook secret with the integrator.

Portal types

A return portal has a type that tells TRAEDE how the portal is used:

Type	Description
traede	TRAEDE's built-in return portal. Cannot be driven by this API.
reversio	Reversio, official TRAEDE partner.
returnflows	Returnflows, official TRAEDE partner.
float	Float, official TRAEDE partner.
custom	A portal built by the brand or a non-partner integrator.

All types except traede are referred to as external in this documentation.

caution

If the portal type is one of reversio, returnflows or float, the API app calling the endpoints must have its internal_code set to the matching value. Any API app may call endpoints for custom portals, provided the portal belongs to the authenticated brand.

Division of responsibilities

TRAEDE and the external portal each own a specific part of the return lifecycle.

TRAEDE owns:

• The return record, its lines, fees and status transitions.
• Inventory regulation when the return is received.
• The credit note that is produced when the return is received.
• Sending the return_received webhook once the credit note is ready.

The external portal owns:

• Authenticating the end customer by email + order number.
• Presenting eligible order lines and claim causes.
• Booking the return shipment with the carrier. TRAEDE does not book return labels for external portals; the portal books them itself and reports labelless_code, track_trace and track_trace_link back to TRAEDE via the upsert endpoint so the values are available in the TRAEDE UI and on downstream documents.
• Issuing the refund in the customer's payment provider (typically Shopify).
• Calling TRAEDE to upsert the return, and finalize it once the refund has been issued.

Return lifecycle

A return created through this API moves through the same statuses as any other return:

approved → received → credited

1. When the portal calls Upsert a return for the first time against a given rma, TRAEDE creates the return in approved status.
2. The portal can replay the same PUT at any point to keep the return in sync - adjusting lines, notes, fees or reporting carrier tracking info (labelless_code, track_trace, track_trace_link) once the label has been booked.
3. The warehouse receives the goods and transitions the return to received inside TRAEDE. At this point TRAEDE creates the credit note in OPEN status (never booked immediately, regardless of the brand's usual settings) and dispatches the return_received webhook.
4. The portal issues the refund, then calls Finalize a return. TRAEDE books the credit note, which moves the return to credited.

Claim causes

Every return line is tagged with a claim cause that describes why the item is coming back (for example "too small", "wrong colour", "damaged on arrival"). Claim causes are configured per brand inside TRAEDE. Each claim cause has a numeric id and a string code.

Return lines may identify a claim cause by either:

• claim_cause_id - the numeric ID.
• claim_cause_code - the string code, looked up case-insensitively on the brand's claim causes.

If two claim causes share the same code on the brand, claim_cause_code is rejected as ambiguous - use claim_cause_id in that case.

Whether a claim cause is mandatory is controlled by the portal's claim_cause_required setting. When it is false, return lines may omit both claim_cause_id and claim_cause_code.

Exchanges

Exchanges are not driven through this API. External portals that want to offer exchanges should create a new order for the exchanged items after the return has been credited. See Exchange flows for the full explanation.

Webhook secrets

Each external return portal has a webhook_secret that TRAEDE generates when the brand creates the portal. This secret is used to HMAC-sign the body of every webhook TRAEDE sends to the portal. See Working with TRAEDE webhooks for how to validate signatures.

Authentication

Every request uses the standard TRAEDE API authentication model. You need:

• An OAuth2 access token, see Authentication.
• An X-Traede-App-Key header, obtained when you register your API app.
• The publicId of an external return portal that belongs to the authenticated brand.