Create a return

Create a return

POST /api/v1/returns

cURL

curl --silent --show-error --fail-with-body --request POST \
  --url 'https://api.stateset.com/api/v1/returns' \
  --header "Authorization: Bearer $STATESET_API_KEY" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "condition": "string",
      "order_item_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 2
    }
  ],
  "notes": "Two-person tent, green — replacement for damaged pole set.",
  "order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reason": "Two-person tent, green — replacement for damaged pole set.",
  "reason_details": "string"
}'

201

{
  "created_at": "2026-08-31T14:22:05Z",
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reason": "Two-person tent, green — replacement for damaged pole set.",
  "refund_amount": "49.00",
  "status": "pending",
  "updated_at": "2026-08-31T14:22:05Z"
}

Confirm your deployment before running this request. This page describes an API contract; a published reference does not establish hosted availability. Check the dated host report and obtain your deployment URL and credentials. Replace the example host if your provisioned service uses a different URL.

Headers

Idempotency-Key · string,null

Optional client-generated key. Replaying the same key with an identical body returns the original response without creating a duplicate; reusing it with a different body returns 422. Scoped per tenant.

Request body

CreateReturnRequest

items · CreateReturnItemRequest[] · required

Show CreateReturnItemRequest

condition · string,null

order_item_id · string (uuid) · required

quantity · integer (int32) · required

notes · string,null

order_id · string (uuid) · required

reason · string · required

reason_details · string,null

Response

ReturnResponse

created_at · string (date-time) · required

customer_id · string (uuid) · required

id · string (uuid) · required

order_id · string (uuid) · required

reason · string · required

refund_amount · string,null

status · string · required

updated_at · string (date-time) · required

Status codes

Code	Meaning
201	Return created
400	Invalid request
422	Idempotency-Key reused with a different body

Using this contract

Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.

cURL

curl --silent --show-error --fail-with-body --request POST \
  --url 'https://api.stateset.com/api/v1/returns' \
  --header "Authorization: Bearer $STATESET_API_KEY" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "condition": "string",
      "order_item_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 2
    }
  ],
  "notes": "Two-person tent, green — replacement for damaged pole set.",
  "order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reason": "Two-person tent, green — replacement for damaged pole set.",
  "reason_details": "string"
}'

201

{
  "created_at": "2026-08-31T14:22:05Z",
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reason": "Two-person tent, green — replacement for damaged pole set.",
  "refund_amount": "49.00",
  "status": "pending",
  "updated_at": "2026-08-31T14:22:05Z"
}