Return request status codes

A return request moves through a small set of statuses from creation to resolution. Some statuses are terminal, once a return request lands there, it stays there.

Status catalogue

Status code	Description	Terminal?
pending	The return request was created and is awaiting merchant review.	No
on_hold	The return request is paused, typically awaiting customer or merchant input.	No
approved	The return has been approved by the merchant. A reverse shipment can now be created.	No
received	The returned items have been physically received at the merchant's location.	No
completed	The return is fully resolved (refund issued, exchange shipped, store credit applied, etc.).	Yes
returned	The reverse shipment has been delivered back to the merchant but the return is not yet marked completed.	No
rejected	The return has been rejected by the merchant.	Yes
cancelled	The return was cancelled (by the customer, the merchant, or the system).	Yes

Typical lifecycle

              ┌───────────┐
              │  pending  │ ◄── return request created
              └─────┬─────┘
                    │
        ┌───────────┼───────────┬───────────┐
        ▼           ▼           ▼           ▼
   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
   │ on_hold │  │approved │  │rejected │  │cancelled│
   └────┬────┘  └────┬────┘  └─────────┘  └─────────┘
        │            │            (final)      (final)
        └─────┬──────┘
              ▼
         ┌─────────┐
         │received │ ◄── reverse shipment delivered
         └────┬────┘
              ▼
         ┌─────────┐
         │completed│ ◄── refund / exchange resolved
         └─────────┘
              (final)

Transition rules

• A return can be approved or rejected only from pending or on_hold.
• A return can be cancelled from pending, on_hold, or approved.
• Once a return is in completed, rejected, or cancelled, no further transitions are allowed.
• received is set when the reverse shipment is delivered back to the merchant.
• completed is set explicitly by the merchant (or automatically by an auto-close rule, see Returns API).

Webhook events

Each transition emits a Return Request webhook event. Listen for these to keep your downstream systems in sync. See Working with webhooks for setup, and the Returns API reference for the full event catalogue.