Returns Workflow

The RMA state machine — authorise, receive, inspect, refund, close.

Returns Workflow

Returns are a state machine, not a flag. Each transition is a distinct call, so the record is auditable end to end.

create ──▶ approve ──▶ markReceived ──▶ complete
   │          │
   │          └──▶ reject
   └──▶ cancel

1. Validate eligibility

Check the return window, item condition, and item eligibility before creating the authorisation. Creating an RMA the policy would reject leaves a record you then have to unwind.

2. Create the return authorisation

import { Commerce } from '@stateset/embedded';
const commerce = new Commerce('./store.db');

const rma = await commerce.returns.create({
  orderId: 'ord_9412',
  lineItems: [{ sku: 'SHOE-RED-10', quantity: 1, reasonCode: 'damaged' }],
});

3. Approve or reject

await commerce.returns.approve(rma.id);
// or
await commerce.returns.reject(rma.id, { reason: 'outside return window' });

4. Add tracking, then receive

await commerce.returns.addTracking(rma.id, {
  carrier: 'usps',
  trackingNumber: '9400111899223817463149',
});

// when the parcel arrives
await commerce.returns.markReceived(rma.id);

markReceived is the point the return becomes real — inventory and financial consequences follow from it, not from approve. Approving an RMA that never arrives costs you nothing.

5. Inspect and complete

Inspection decides restock, refurbish, or reject. Then:

await commerce.returns.complete(rma.id);

complete finalises the record and settles order, inventory, and financial state together.

Cancelling

await commerce.returns.cancel(rma.id);

Finding returns

await commerce.returns.listForOrder('ord_9412');
await commerce.returns.listForCustomer('cus_1042');
await commerce.returns.listPending();          // the work queue
await commerce.returns.get(rma.id);
await commerce.returns.count();

listPending() is the operational view — everything authorised but not yet resolved. That’s the queue a returns agent should work from.

Why the transitions are separate

A single status field you overwrite loses the history. Because each step is its own call, the record answers when it was approved, when the parcel landed, and who completed it — which is what a chargeback or an audit actually asks.

update_return is deliberately not exposed as a single tool: its input is complex and unbounded. The status-transition methods above cover the practical paths.

Related

• Order Lifecycle
• Returns Quickstart
• Finance & Accounting — where refunds land