Skip to main content

Recommended data flow

This section describes the end-to-end data flow between an external return portal and TRAEDE, from the moment the brand configures the portal to the moment the customer's credit note is booked.

1. Brand configures the portal in TRAEDE​

  1. A brand administrator creates an external return portal inside TRAEDE and picks its type (reversio, returnflows, float or custom).
  2. TRAEDE generates a public_id and a webhook_secret for the portal. The admin enters the portal's webhook_endpoint where TRAEDE should deliver webhooks.
  3. The admin shares the public_id and webhook_secret with the integrator, out-of-band.

See Installing the Return Portal in TRAEDE for the full setup steps.

2. A customer starts a return on the external portal​

  1. The customer authenticates with their email and order number.
  2. The portal fetches the eligible order and claim causes from its own systems or from TRAEDE.
  3. The customer selects which lines to return, the claim type (return, claim or exchange) and a claim cause.
  4. The portal decides on return fees and any Shopify gift-card refund options.

3. The portal registers the return in TRAEDE​

  1. The portal calls Upsert a return with the customer email, order number, its own rma identifier and the return lines.
  2. TRAEDE validates the order, the variants and the claim causes, then creates the return in approved status and responds with created: true.
  3. The portal stores the TRAEDE return.id for reference if needed. All subsequent calls can still use just the portal's own rma - TRAEDE's numeric ID is not required.

4. The portal books the return shipment and reports tracking info​

  1. The portal books the return label or dropoff code with its carrier. TRAEDE does not book return labels for external portals.
  2. Once the carrier has returned a labelless_code, track_trace or track_trace_link, the portal replays the Upsert a return call with the same rma and those fields populated. This updates the return in place; the numeric return ID and the existing line IDs are preserved.

5. The warehouse receives the goods​

  1. The customer ships the goods.
  2. When the goods arrive, the warehouse marks the return as received inside TRAEDE. This can happen by a warehouse operator clicking in TRAEDE, or by a 3PL integration marking the return as received via the 3PL API.
  3. TRAEDE regulates inventory and creates a credit note for the return in OPEN status. External portals always get OPEN credit notes - the brand's "book immediately" settings are ignored for external portals.
  4. TRAEDE dispatches a return_received webhook to the portal's webhook_endpoint. See Working with TRAEDE webhooks for the payload and signature format.

6. The portal issues the refund​

  1. On receiving the webhook, the portal issues the refund in the customer's payment provider (typically Shopify).
  2. The portal computes the final refunded amount.

7. The portal finalizes the return​

  1. The portal calls Finalize a return with the refunded total_price_after_vat, keyed by the same external rma.
  2. TRAEDE compares the provided amount against the sum of total_price_after_vat across the return's credit notes, with a ±0.01 tolerance.
  3. If the amounts match, TRAEDE books all OPEN credit notes for the return, which moves it to credited.
  4. If the amounts do not match, TRAEDE returns a validation error and the portal must either adjust the return with another Upsert a return call and retry, or contact the brand.

Replaying the PUT​

The upsert endpoint is idempotent. A portal can safely re-send the same PUT body for the same rma at any time. Between creation and the return being received, each PUT replaces the line set:

  • A line that is present in the new body and already exists on the return keeps its TRAEDE line ID (first by exact natural key, then by variant_id).
  • A line in the new body that has no match creates a new line on the return.
  • A line on the return that is absent from the new body is deleted.

See Line merge behavior for the full matching rules.

Line updates are not accepted once the return has transitioned to received or credited.