StateSet API Docs

This reference covers @stateset/embedded 1.35.1. The returns quickstart contains a complete program that creates a shipped order, returns one item, verifies an idempotent retry, and follows the RMA through receipt.

1. Validate eligibility

Read the order before creating a return. Verify that it is shipped, that the requested line belongs to it, and that the quantity is eligible. Apply your business’s return policy before approving a request; the record’s existence alone is not an approval.

2. Create the return authorization

In this snippet, order is a shipped order read from the same database and commerce is your Commerce instance:

const request = {
  orderId: order.id,
  reason: 'damaged',
  reasonDetails: 'One mug arrived cracked',
  idempotencyKey: `return-${order.id}-mug-1`,
  items: [{ orderItemId: order.items[0].id, quantity: 1 }],
};
const rma = await commerce.returns.create(request);

Use items and orderItemId; this Node method does not accept lineItems keyed only by SKU. The new return’s status is requested. Preserve the same key and request for a retry of this operation. The quickstart checks that replay returns the same RMA ID.

3. Approve or reject

const approved = await commerce.returns.approve(rma.id);

For a requested RMA that should be rejected, the alternative is commerce.returns.reject(rma.id, 'Reason for rejection'). The second argument is a string. Choose one path based on the current state and the policy decision.

4. Add tracking, then receive

const inTransit = await commerce.returns.addTracking(rma.id, 'RETURN-TRACK-001');
const received = await commerce.returns.markReceived(rma.id);

addTracking takes a tracking-number string and moves the approved RMA to in_transit. markReceived moves it to received. In a production workflow, call receipt after the parcel has actually arrived; updating the record does not contact a carrier or inspect an item.

5. Inspect and complete

A disposition records how each returned item is handled: restock, quarantine, refurbishment, scrap or return to vendor. The engine rejects completion when items lack dispositions.

Node binding 1.35.1 exposes returns.complete(id) but does not expose an item-disposition setter or the completion write-off option. The quickstart therefore stops at received and verifies that premature completion is rejected. Use an integration that supports the disposition step before attempting an end-to-end production completion flow.

After the required item handling has been recorded through a supported interface, completion is a separate transition. Treat any refund as its own financial operation and verify it in the payment system. Receiving or completing an RMA alone is not proof of a payment-provider refund.

Cancelling

For an RMA whose current state permits cancellation:

const cancelled = await commerce.returns.cancel(rma.id);

Cancellation is subject to state and disposition guards. Read the record and handle a rejected transition; do not use cancellation as a generic error-cleanup step after goods have been received or dispositioned.

Finding returns

const current = await commerce.returns.get(rma.id);
const orderReturns = await commerce.returns.listForOrder(order.id);
const customerReturns = await commerce.returns.listForCustomer(order.customerId);
const pending = await commerce.returns.listPending();
const count = await commerce.returns.count();

These methods return the Node binding’s records. For example, ReturnOutput includes the return ID, order ID, status, reason, version, creation time and optional idempotency key. Do not assume it contains the full item-disposition or payment-provider record.

Returns quickstart — complete executable example and expected output
Order lifecycle — the original order’s state
Verify a refund decision — policy authorization before an action
Language bindings — choose and inspect an interface

Last modified on September 20, 2026

Get started

Build your first integration

Operate and improve

Resources and support

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Returns Workflow

1. Validate eligibility

2. Create the return authorization

3. Approve or reject

4. Add tracking, then receive

5. Inspect and complete

Cancelling

Finding returns

​1. Validate eligibility

​2. Create the return authorization

​3. Approve or reject

​4. Add tracking, then receive

​5. Inspect and complete

​Cancelling

​Finding returns

​Related

1. Validate eligibility

2. Create the return authorization

3. Approve or reject

4. Add tracking, then receive

5. Inspect and complete

Cancelling

Finding returns

Related