logo
Try for free
  • Product
  • Solutions
  • Developers
  • Resources
  • AI
  • Pricing
  • Log in
  • Create a store
  • Product

  • AI
  • Pricing
  • Try for free
  • Log In
  • Merchandising

  • Operations

  • Building

  • Integrations

  • Products

    Powerful modeling and versatile presentation of your entire catalog.

  • Subscriptions

    Sell recurring physical and virtual products alongside one-time offerings.

  • Discounts

    Get the sale with coupons, BXGY promotions, and automatic discounts.

  • Wholesale

    Sell B2B like it's DTC, along with volume pricing, customer groups, and invoicing.

  • Content

    Manage all your products content through the admin dashboard.

  • Users

    Multi-store admin accounts and role-based permission controls.

  • Customers

    Manage customer info, generate reports, and see buyer activity.

  • Orders

    Edit orders anytime and get the right information for smooth fulfillment.

  • Fulfillment

    Ship from multiple locations, track inventory, and split shipments.

  • Reporting

    Monitor your store's performance to ensure you have visibility across the business.

  • Storefronts

    Swell storefronts are fully customizable, allowing you to create just the right experience.

  • Checkouts

    Use our hosted checkout, integrate with a partner, or build a custom flow.

  • Payments

    Connect multiple gateways simultaneously, store cards, and split payments.

  • Internationalization

    Go global with region-specific languages, pricing, and payment methods.

No-code integrations

Connect with 40+ services for marketing, payments, fulfillment, automation, and more.

See all integrations →

Use Cases

  • Direct-to-consumer

    Tell your story and give customers a unique shopping experience

  • Subscriptions

    Sell personalized subscription bundles, memberships, and one-time items together

  • B2B/B2C

    Support retail and wholesale customers from one catalog and dashboard

  • Marketplaces

    Create a B2B or B2C marketplace with multi-vendor carts and split payouts

Customer Stories

  • Spinn Coffee

    A coffee revolution sparked by a connected machine and marketplace

  • Smashing magazine

    Global tax and shipping for complex product bundles

  • Infinitas Learning

    Delievering leading educational experiences in Europe

All customer stories →

Documentation

  • Quickstart

  • Backend API reference

  • Frontend API reference

  • Guides

  • Core concepts

  • Storefronts

  • Headless commerce

Community

  • GitHub

  • Discussion forum

  • Changelog

  • API status

Resources

  • Help Center

    The latest industry news, updates and info.

  • Customer stories

    Learn how our customers are making big changes.

  • Become a partner

    For agencies creating innovative commerce experiences.

Latest blog posts

  • deep-dive-app-functions
    Nov 06, 2025

    Build smarter workflows with App Functions

  • storefronts-v2-and-the-future-of-swell-apps
    Oct 22, 2025

    Storefronts V2 and the future of Swell Apps

  • Changelog

  • API Status

  • Contact us

  • Swell Merch

Blog

How to Build a Returns and RMA Workflow for a Headless Store in 2026

How to design returns and RMAs in a headless store: policy as data, state side effects, refund vs exchange vs credit, return platforms and the Swell API mapping.

Swell Team | October 30, 2026
Woman packing cardboard boxes beside a clothing rack.

A returns workflow in a headless store is an order running backwards. Money goes back to the customer (or onto their account), goods come back into the warehouse (or into the damaged pile), and every step needs a message that tells the customer where things stand. The return merchandise authorization (RMA) is the record that ties those three reversals together.

The platform gives you the ledger: return records, refunds against payments, account credit and the events that fire when any of them change. It does not decide your return window, whether you push exchanges over refunds, who pays for the label, when a refund is released or what counts as abuse. Those are operator decisions, and in a headless build you encode them yourself, either in your own service or in a returns platform you connect.

This guide covers those decisions, an RMA state model built around its money, inventory and customer side effects, a refund versus exchange versus credit matrix, an accurate look at Loop, ReturnGO, AfterShip Returns and Narvar, return-abuse rules, subscription renewal returns, and how the pieces map to what Swell documents for returns, refunds and credits.

Key Takeaways

  • Treat every RMA state as three side effects: what happens to the payment, what happens to inventory, and what the customer is told. If a state changes none of them, it probably is not a state.
  • Express your policy as data (windows, eligible categories, fees, resolution options) so the portal, the support team and the warehouse all read the same rules.
  • Exchanges and store credit keep revenue, but store credit is a liability on your books until it is spent or expires under the rules that apply to you.
  • Release money after inspection by default, and earn the right to release it earlier (on first carrier scan, or instantly) with customer history.
  • On Swell, the return record, refunds against payments, account credits and their events are documented in the Backend API. Portal UI, approval rules and label purchase are yours to build or buy.

An RMA Is the Order's Reversal, Not a Support Ticket

Teams that start returns in the help desk end up with a ticket that says "refund approved" and no record of which line items, which quantities, how much tax, or whether the box ever arrived. Model the RMA as a first-class commerce object linked to the original order and its line items, with quantities that can never exceed what was fulfilled and not already returned.

Returns are not a rounding error. The NRF and Happy Returns 2025 report estimated that 19.3% of online sales would be returned in 2025. At that volume, every manual step in the reversal shows up as labor cost, and every gap between "refunded" and "received" shows up as loss.

Decisions the Platform Will Not Make for You

Return windows and eligibility, stored as data

Write the policy as fields a program can evaluate, not as a paragraph on the returns page. A workable minimum per product or category:

  • Window in days, counted from delivery rather than order date, with a separate holiday extension date if you run one.
  • Returnable flag for final sale, personalized, hygiene-sensitive and perishable items.
  • Allowed resolutions (refund, exchange, store credit) and whether any of them carry a fee.
  • Condition requirements (tags attached, unworn, original packaging) that the inspector checks later.
  • Jurisdiction overrides. In the EU, consumers buying at a distance can withdraw within 14 days without giving a reason, with exceptions such as custom-made goods and perishables. Your rule engine should never offer less than the law in the shipping destination.

When the rules live in data, the portal can show a customer exactly which items are eligible and why, and support can explain a denial by pointing at a field instead of a judgment call.

Who pays for the return trip

Return shipping is a cost you allocate, not a cost you avoid. The common options are free returns, a flat label fee deducted from the refund, free returns only for exchanges or store credit, and customer-arranged shipping. Two rules sit outside your preference: defective or wrong items should ship back at your cost (the EU guidance above says the trader pays for returning a defective product), and any fee has to be disclosed before purchase.

Prepaid labels in every box are cheaper than they sound when the carrier bills on use. Shippo, for example, documents pay-on-use return labels for USPS, FedEx and UPS that are free to print and charged only when scanned.

Exchange-first or refund-first

An exchange keeps the sale and usually costs you a second outbound shipment. A refund ends the relationship for that order. Exchange-first portals present the swap before the refund, and some offer a bonus on store credit or same-value exchanges. Decide what an uneven exchange does: if the new item costs more, you collect the difference; if it costs less, you refund or credit the gap. Also decide whether the replacement ships before the original arrives (better experience, more exposure to abuse) or after inspection.

Store credit is a liability

Issuing credit instead of cash feels like keeping the money, but finance will book it as an obligation until the customer spends it. Decide up front whether credit expires, whether it is transferable, whether a credit bonus is funded by marketing or by margin, and how unused credit is handled under the gift card and unclaimed property rules where you operate. Give finance a report of outstanding credit by issue month, not a single balance.

The RMA State Model, Told Through Its Side Effects

Each state below lists the three things that change when an RMA enters it. Keep the states few and the transitions explicit; "canceled" and "declined" can be reached from any state before the goods are received.

Requested

  • Payment: nothing moves. Calculate the estimated refund (item price less allocated discount, plus tax on that base, minus any fee) and show it as an estimate.
  • Inventory: nothing moves. The units are still in the customer's home.
  • Customer: confirmation with the RMA number, the items and quantities, and what happens next.

Approved or declined

  • Payment: still nothing, unless the customer chose a paid exchange upgrade and you collect the difference now.
  • Inventory: for an exchange that ships early, reserve the replacement unit. For everything else, no change.
  • Customer: approval with shipping instructions, or a decline that cites the specific rule (window passed, final sale item).

Label issued

  • Payment: if the customer pays for the label, record the fee as a deduction on the eventual credit rather than charging the card separately.
  • Inventory: no change. Store the carrier, service and tracking number on the RMA.
  • Customer: the label or QR code, the drop-off options and the deadline for sending.

In transit

  • Payment: for customers you trust, this is where an early refund can release on first carrier scan. For everyone else, wait.
  • Inventory: expected inbound units, useful for the warehouse's receiving plan, not sellable stock.
  • Customer: a tracking update, and a reminder if no scan appears before the deadline.

Received

  • Payment: still held, unless policy releases on receipt rather than inspection.
  • Inventory: units are physically on hand but not sellable. Count what arrived against what was approved; a short count is the first abuse signal.
  • Customer: "we have your return" with an expected resolution date.

Inspected

  • Payment: the final amount is fixed here. Deduct for missing items, damage beyond normal handling, or a restocking fee your policy allows.
  • Inventory: each unit gets a disposition: restock as sellable, send to refurbishment, liquidate, or write off as damaged.
  • Customer: if the amount differs from the estimate, say why before the money moves.

Resolved: refund, exchange or store credit

  • Payment: a refund to the original payment method, a refund converted to account credit, or credit applied to a replacement order. Partial resolutions are normal (one item refunded, one exchanged).
  • Inventory: the restock entries post, and for an exchange the replacement order commits its own unit.
  • Customer: the amount, the method, and how long the bank usually takes to show it.

Close the RMA when the refund has succeeded, the credit has posted or the exchange order has shipped. A refund that fails at the gateway should reopen the resolution step, not leave the RMA marked done.

Refund vs Exchange vs Store Credit: A Decision Matrix

Refund to the original payment method

  • Use when: the customer asks for their money, the item is defective, or local law requires it.
  • Payment effect: cash leaves. With card processors, original processing fees are often not returned; Stripe states its processing fees from the original transaction are not returned on refunds.
  • Margin effect: you lose the sale plus both shipping legs and any non-refundable fees.
  • Failure mode: in rare cases the refund fails (for example a closed bank account), so you need a fallback method and a way to reopen the resolution.

Exchange

  • Use when: the issue is fit, size or color and you have the replacement in stock.
  • Payment effect: usually none on even exchanges; a charge or partial refund on uneven ones.
  • Margin effect: the sale survives; you absorb the extra outbound shipment.
  • Failure mode: the replacement goes out of stock between approval and fulfillment, so check stock at resolution time, not only at request time.

Store credit

  • Use when: the item is outside the cash-refund window but still within a credit window, or the customer chooses credit (optionally with a bonus).
  • Payment effect: no cash leaves now; a liability is created.
  • Margin effect: best on paper, but only once the credit is redeemed; a bonus is a real cost.
  • Failure mode: credit offered as the only option where local law requires a refund.

Return Portals and Labels: What Each Option Actually Does

Every serious returns platform does the same core job: an order lookup page, policy rules, label generation and a resolution step. The differences that matter for a headless store are how order data gets in, and how outcomes get back to your commerce platform.

Building it yourself

You own the portal UI, the policy rules and the RMA records, and you buy labels from a shipping API. This fits teams that already run a custom storefront and want returns logic to sit next to the rest of their order code. The cost is everything a platform would otherwise handle: label voids, carrier tracking, reminder emails and reporting.

Loop

Loop's documentation for platforms without a prebuilt app describes commerce data APIs that receive pushes of products and variants, orders, customers, (if you offer exchanges) locations and inventory, and optionally collections, with products synced before orders and orders covering at least your return window. Its return action APIs let your systems process, flag, close or cancel a return. For labels, Loop supports an external connector for label providers it does not integrate with directly. Its pricing page lists Essential from $155 per month and Advanced from $340 per month.

ReturnGO

ReturnGO's pricing page lists API and webhooks on Pro (from $297 per month) and Enterprise, and support for any platform on Enterprise. Its help center says a custom ecommerce platform connects through its Platform API on an Enterprise plan. The API overview covers creating RMAs externally, generating labels, validating returned items and syncing refund transactions.

AfterShip Returns

AfterShip's getting started guide lists Shopify, BigCommerce, WooCommerce, Squarespace and Magento integrations, plus label generation and refund and exchange options. Its warehouse integration guide uses webhooks such as return.shipment.provided, lets the warehouse mark items received and assign a condition grade, and is limited to Enterprise customers. A custom headless store should confirm the order-sync path with AfterShip before committing.

Narvar

Narvar targets larger retailers. Its returns app page describes 200,000+ drop-off locations, printerless and boxless returns, exchanges of the same or different value, and store credit bonuses, and its returns solution page covers return fraud detection and integrations with Shopify, BigCommerce, Magento and Salesforce Commerce Cloud. Expect an enterprise sales process and integration project rather than a self-serve setup.

Return-Abuse Rules Worth Encoding

The same NRF and Happy Returns report estimated that about 9% of all returns are fraudulent, with overstated quantities, empty-box returns and decoy items among the schemes retailers reported, alongside wardrobing and bracketing. Rules that target those patterns without punishing normal customers:

  • Inspection gate by default. Money releases after inspection; early release is a privilege based on order history.
  • Serial returner thresholds. Track return rate and count per customer over a rolling window, and route accounts over the threshold to manual approval or credit-only resolutions.
  • Weight and count checks at receiving. Compare the received package weight and unit count with what was approved to catch empty-box and short returns.
  • Swap detection. Record serial numbers, lot codes or tamper tags at shipment and check them on receipt.
  • Wardrobing signals. Require tags attached for apparel, set a shorter window for occasion wear, and photograph returned goods at inspection.
  • Bracketing limits. If the same customer orders three sizes and returns two every time, consider offering fit guidance or an exchange instead of blocking the order.

Subscription Renewal Returns

A shipped renewal that the customer did not want is a normal return with one more decision: what happens to the subscription. Refund or credit the renewal order like any other return, then pick one of three follow-ups.

  • Pause: the customer wants the product, just not this month. On Swell, a subscription can be paused with `paused`, and a resume can be scheduled with `date_pause_end` or `pause_skip_cycles`.
  • Skip ahead: use a dated resume so the next order lands when the customer has used up stock.
  • Cancel: set `canceled`, with `cancel_at_end` to choose between immediate cancellation and the end of the billing period, and record `cancel_reason`.

Ask the customer which they want inside the return flow, since a return is a strong churn signal. For retention offers beyond this point, see how to reduce subscription churn.

Implementing Returns on Swell

Everything in this section is documented in Swell's Backend API reference. What Swell does not document (a customer-facing returns portal, approval rules, label purchase) is the part you build or connect.

The return record

A return is created with `POST /returns` against an `order_id` and holds `items` that reference `order_item_id`, `product_id`, `variant_id` and `quantity`. Each item tracks `quantity_received` and `quantity_restocked`, and the return rolls those up into `item_quantity_received`, `item_quantity_restocked` and a `received` flag. The return also carries `reason_code`, internal `notes`, `tracking_code`, `carrier` and `service`, plus money fields: `restock_fee`, `shipment_total` (shipping credited back), `extra_credit` (compensation for inconvenience) and the computed `credit_total` and `credit_tax`. A return can be marked `canceled`.

Swell's docs describe a return as carrying the value to apply to an order, "which in turn may prompt an administrator to issue a refund". In other words, creating a return records the reversal; it does not move money on its own.

What changes on the order

The order reflects returns through fields such as `item_quantity_returned`, `item_quantity_returnable`, `return_item_total`, `return_item_tax` and `return_total`. Use `item_quantity_returnable` as the eligibility ceiling in your portal. The order's `payment_balance` is positive when a refund is due, which makes it a simple check for "returns recorded but not yet paid out".

Issuing the refund

Refunds are issued against a payment with `POST /payments:refunds`, passing `parent_id` (the payment), `amount` and optionally `method`, `reason` and `reason_message`. The method defaults to the original payment method and can be `account` to refund to the customer's account credit. A refund's `status` is `pending`, `void`, `error` or `success`, and `async` marks refunds the gateway settles later. The docs note the sum of refunds can't exceed the payment amount, and related orders update their refund totals automatically.

Store credit and exchanges

Account credits are created with `POST /accounts:credits` (`parent_id`, `amount`, `reason`, `reason_message`), and the account's `balance` holds the total. For an exchange, one way to do this with documented fields is to put the return value on the customer's account, then create the replacement order with `account_credit_applied` (and `account_credit_amount` if you cap it) so the balance pays for it. Any uneven difference is charged or refunded through the normal payment and refund calls.

Restocking

Disposition is the warehouse's call; the commerce record follows it. The return item's `quantity_restocked` records what went back to inventory, and the stock model has a `returned` reason for those adjustments (and `damaged` for write-offs). Check whether your restock flow already writes the stock entry before adding a second one, and record damaged units as damaged rather than returned.

Events to listen for

Swell's event list includes `return.created`, `return.updated` (including received and restocked quantity changes), `return.received`, `return.canceled`, `payment.refund.succeeded`, `payment.refund.failed`, `payment.refund.voided` and `account.credit.created`, plus `subscription.paused` and `subscription.canceled` for renewal returns. Use them to send the customer messages for each state and to reopen an RMA when a refund fails. For how to receive and process webhooks reliably at volume, see the checkout performance guide.

The pre-approval request

Swell's return model starts once you have decided to accept the goods, so many stores keep the customer's request (photos, free-text reason, eligibility result, inspection grade) in a custom model and create the Swell return on approval. The custom-model approach is the same one described in the B2B quote-to-order workflow.

Reality Check: Payments, Tax and Cost

  • Refund timing is the bank's, not yours. Stripe says customers see a refund about 5 to 10 business days after it is initiated, and refunds issued soon after the charge may appear as a reversal instead. Put that in the resolution message.
  • Refund destination limits. Stripe refunds go back only to the original payment method. Issuers usually route refunds on expired or canceled cards to a replacement card; in the rare case a refund fails, your fallback is store credit or another method plus a support conversation.
  • Tax reverses with the goods. Refund tax on the returned taxable base at the original rate; the sales tax and VAT guide covers discounts, shipping tax and partial returns.
  • Fees you keep paying. Original processing fees, the outbound shipment and the return label are sunk once the item comes back. Track cost per return alongside return rate.
  • Platform cost. Swell's published plans include a set amount of annual revenue (from $50K on Starter at $29/month billed yearly to $5M on Unlimited at $2,250/month), with an overage rate above that which falls as you upgrade (2% on Starter down to 0.4% on Unlimited).

How to Choose: Build, Buy or Hybrid

  • Build if you have a small catalog, a developer who already owns the order code, and fewer returns than would justify a returns platform's monthly fee. Use Swell's return, refund and credit records directly and buy labels from a shipping API.
  • Buy if exchange conversion, drop-off networks and a polished portal matter more than control, and you are ready for an order-sync integration. Confirm which plan includes API access for a custom platform before you sign.
  • Hybrid if you want a vendor's portal and labels but your own approval and abuse rules. Keep the RMA's financial outcome in Swell either way, so refunds, credits and reporting live with the order.

Whichever you pick, write the policy as data first. The integration choice is easier once you know what the rules are.

Frequently Asked Questions

Should refunds be released when the label is scanned or after inspection?

Default to inspection, and release earlier only for customers with a clean history. Early release improves the experience but turns empty-box and swap returns into direct losses.

Does creating a return in Swell refund the customer?

No. A return records the items, quantities and credit value on the order. You issue the refund separately against the payment, to the original method or to account credit.

How do I handle an exchange for a more expensive item?

Credit the returned item's value, create the replacement order, apply the credit, and charge the customer for the difference. If the new item costs less, refund or credit the gap.

Can a customer get store credit instead of a refund to their card?

Yes, if your policy offers it and local law does not require a cash refund. On Swell, a refund can use the `account` method, or you can create an account credit directly.

What should happen to inventory when a return arrives?

Nothing sellable until inspection. Then each unit is restocked, refurbished or written off, and the stock adjustment is recorded with the matching reason.

How should I treat a returned subscription renewal?

Refund or credit the renewal like any return, then ask whether the customer wants to pause, skip ahead or cancel, and update the subscription accordingly.

Build your store on Swell

Headless commerce with a full API on every plan, native subscriptions and custom data models. Start a store and see how it fits your build.

Try Swell for freeTalk to us

Next-level commerce for everyone.

X.comGitHubLinkedIn

Subscribe to our newsletter for product updates and stories

Resources

Help CenterDeveloper CenterCommunityChangelogLearnSwell Merch

Use cases

SubscriptionsB2B WholesaleMarketplaceOmnichannelDirect-to-consumerEnterprise

Explore

FeaturesPricingIntegrationsCustomer stories

Developers

OverviewDocumentationGuidesStorefrontsHeadlessSwell Apps

Company

BlogAbout usPartnersContact us

© 2026 Swell. All rights reserved.

Privacy PolicyTerms of Service