Documentation

REST API

Build a custom returns flow on the headless core.

The REST API exposes the full returns lifecycle. All write endpoints accept an idempotency key.

Create a return

http

POST /v1/portal/returns
Content-Type: application/json
Idempotency-Key: rt_2048_v1

{
  "order_id": "2048",
  "line": { "sku": "knit-navy-m" },
  "reason": "FIT_TOO_SMALL_SHOULDER",
  "resolution": "EXCHANGE",
  "exchange_size": "L"
}

Advance state

Returns move through a state machine: draft → submitted → approved → in_transit → received → graded → closed (with rejected, flagged, and cancelled branches). Each transition is a single merchant endpoint.

http

POST /v1/merchant/returns/:id/:event

# :event ∈ approve | reject | flag | unflag
#         ship | receive | grade | close

# fit signals are emitted at: received, graded, closed

The draft-return resource exposes HATEOAS links, making the API friendly to autonomous agents (OAuth 2.1 + PKCE).

Policy engine

Webhooks