Docs
Sign in

Returns portal

Updated May 26, 20263 min read

The returns portal is where customers raise return requests. Customers typically arrive from an order-confirmation email or a help-center link. They look up their order, pick the items they want to return, pick a reason, and submit.

Behind the scenes, the portal calls the Returns API to create a return request. From there, the Return request model takes over: approval, reverse shipment booking, and the rest of the lifecycle.

The portal is part of Carriyo's Returns add-on. Your tenant must be subscribed for the portal to be active.

How customers reach the portal

The returns portal is a CX app like Tracking and Feedback. It is served from a per-merchant URL on Carriyo's default domain, or from a custom domain (for example, returns.brand.com). The custom-domain setup mirrors branded tracking: two CNAMEs, one to point at Carriyo and one for SSL validation. See Post-purchase CX for the full setup.

Order lookup

The customer enters their order reference plus one of:

  • Email. Validated against dropoff.contact_email on the order's shipments.
  • Phone. Validated against dropoff.contact_phone.

The merchant configures which methods are allowed via orderLookupMethods in Returns Settings. Both can be enabled, in which case the customer can use either.

Item selection and eligibility

Once the order is found, the portal shows the order's lines with per-line eligibility computed server-side:

  • Already-returned check. Items already in an active return request are subtracted from the available quantity. The customer can't ask for four units back when they've already opened a return for two.
  • Delivered-only filter (optional). If allowUndeliveredItems is false in Returns Settings, only items on DELIVERED shipments are eligible. This is the most common configuration.
  • SKU-level non-returnable flag. If a product SKU is marked non-returnable in its product metadata, the portal disables the line.
  • Return window. allowedDaysForReturn is read from Returns Settings and enforced when the page renders.

Lines that fail eligibility are still shown (but disabled), with the reason explained inline.

Reason, comment, and photo

For each item, the customer picks a reason from the merchant's configured list. Each reason can require additional input:

  • requireComments. The customer must enter a free-text comment.
  • requireImages. The customer must upload at least one photo (JPG, PNG, or WebP, up to 5 MB each).
  • requireItemCondition. The customer must describe the condition from the merchant's configured condition codes.

These three flags are set per reason in Returns Settings, so defective might require a photo while changed mind doesn't.

Submission and outcome

When the customer submits, the portal creates a return request via the Returns API. The auto-approve flag on the chosen reasons determines what happens next:

  • If every item's reason is auto-approve, the request is approved immediately. The portal then shows the next step: return instructions, drop-off info, or the label.
  • If any item's reason isn't auto-approve, the request stays pending and the customer is told the request is under review. The merchant decides in the Dashboard.

Branding and theming

The portal inherits the merchant's brand theme (logo, colors, typography) and can override any part of it. Configured at CX Apps → Returns Portal. Per-locale content is supported for all customer-facing strings (order-number placeholder, success message, terms and conditions, shipping instructions, footer).

Iframe embedding

The returns portal supports iframe embedding (for example, "My Account → Returns"). The setup mirrors branded tracking:

  • Enable iframe mode on the returns app.
  • Allowed parent origins. A comma-separated list. Carriyo enforces via Content-Security-Policy: frame-ancestors.

How it fits with other modules