Queek docs
Merchant endpoint reference

Returns

GET
/returns

Requires scope merchant-returns-read.

Lists the store’s returns, newest first, with cursor pagination (limit + starting_after, has_more/next_cursor). status keeps one of requested, open, declined, cancelled or closed; order_id (a p_id or UUID) keeps the returns of one order and lists nothing for an order that is not this store’s; updated_since (RFC 3339 with an offset) keeps returns changed at or after that moment, for a poller that resumes from a checkpoint. Every row is the object GET returns/{return} answers: its status, source, order, line_items (units asked, received and put back on the shelf, with the reason), the customer_message the store gave the customer and the dates of each state. Every id is a p_id. customer_note is present only with merchant-customers-contact-read; the store’s own note is never returned to a key or an app. The window moves as rows change, so a walk through pages is not a snapshot: poll with updated_since for returns the store records and deduplicate on id and updated_at.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

status?|

Keep one status: requested, open, declined, cancelled or closed.

Value in

  • "requested"
  • "open"
  • "declined"
  • "cancelled"
  • "closed"
  • null
order_id?|

Keep the returns of one order, its p_id or UUID. An order that is not this store's lists nothing.

Match^(?:[1-9][0-9]{0,17}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
updated_since?|

Keep returns changed at or after this moment (RFC 3339 with an explicit offset), oldest checkpoint a poller resumes from.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/returns?limit=2&order_id=58213" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": 1001,      "status": "open",      "source": "api",      "order": {        "id": 58213,        "order_number": "26-0924-58213"      },      "line_items": [        {          "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",          "title": "Smokehouse Party Pack",          "variant_title": null,          "quantity": 2,          "received_quantity": 1,          "restocked_quantity": 1,          "reason": "defective"        }      ],      "decline_reason": null,      "customer_message": "Send it back to our New York shop; we will refund you when it arrives.",      "requested_at": "2026-10-02T10:20:00+01:00",      "opened_at": "2026-10-02T11:05:00+01:00",      "reopened_at": null,      "declined_at": null,      "closed_at": null,      "cancelled_at": null,      "refunded": false,      "refunded_amount": "0.00",      "currency": "USD",      "created_at": "2026-10-02T10:20:00+01:00",      "updated_at": "2026-10-05T15:30:00+01:00",      "customer_note": "The zip broke on first use."    },    {      "id": 1001,      "status": "requested",      "source": "api",      "order": {        "id": 58213,        "order_number": "26-0924-58213"      },      "line_items": [        {          "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",          "title": "Smokehouse Party Pack",          "variant_title": null,          "quantity": 2,          "received_quantity": 0,          "restocked_quantity": 0,          "reason": "defective"        }      ],      "decline_reason": null,      "customer_message": null,      "requested_at": "2026-10-02T10:20:00+01:00",      "opened_at": null,      "reopened_at": null,      "declined_at": null,      "closed_at": null,      "cancelled_at": null,      "refunded": false,      "refunded_amount": "0.00",      "currency": "USD",      "created_at": "2026-10-02T10:20:00+01:00",      "updated_at": "2026-10-02T11:05:00+01:00",      "customer_note": "The zip broke on first use."    }  ],  "has_more": true,  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMiAxMDoyMDowMCIsImlkIjoiMDE5YTZjMjAtNWU0MS03YTUyLTliNjMtMGMxZDJlM2Y0YTAyIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}
POST
/returns

Requires scope merchant-returns-create.

Records that lines of an order come back. order_id is a p_id or UUID of one of this store’s orders; each line_items[] names a different line of it (order_item, the line id from the order), a quantity and a reason (size_too_small, size_too_large, unwanted, not_as_described, wrong_item, defective, style, color or other). A line may not ask for more than GET orders/{order}/returnable shows (422 return_line_invalid, which also answers a line that is not the order’s, a repeated line and an empty list); an order that was not delivered or completed, or that was cancelled or rejected, answers 422 order_not_returnable. status is requested (the default: it waits for the store, POST returns/{return}/approve or /decline) or open (the store already agreed, so goods may be received at once). customer_note is what the customer said and is readable only with merchant-customers-contact-read (the customer sees it, and customer_message, with the return on their own order page); note is for the store only: it is never returned to a key or an app and never sent in a webhook (only the store’s dashboard shows it back). source (api for a key, app for an app) is set by Queek from the credential and cannot be sent. Send an Idempotency-Key: a retried create without one records a second return that reserves the same units again, while a retry with the same key and body answers the first return. Creating a return moves no stock and no money, changes no order status and refunds nothing. Another store’s order answers 404. Answers 201 with the return. Fires returns/create.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Record that some lines of an order come back. Which lines can come back, and whether the order can be returned at all (it must have been delivered or completed and not cancelled or rejected), is refused with 422 return_line_invalid or order_not_returnable. The order is always one of the caller's own store, never taken from anywhere else.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/returns" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "order_id": "58213",    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "quantity": 2,        "reason": "defective"      }    ],    "status": "requested",    "customer_note": "The zip broke on first use.",    "note": "Check the seam."  }'
{  "status": "success",  "message": "Return created.",  "data": {    "id": 1001,    "status": "requested",    "source": "api",    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "received_quantity": 0,        "restocked_quantity": 0,        "reason": "defective"      }    ],    "decline_reason": null,    "customer_message": null,    "requested_at": "2026-10-02T10:20:00+01:00",    "opened_at": null,    "reopened_at": null,    "declined_at": null,    "closed_at": null,    "cancelled_at": null,    "refunded": false,    "refunded_amount": "0.00",    "currency": "USD",    "created_at": "2026-10-02T10:20:00+01:00",    "updated_at": "2026-10-02T11:05:00+01:00",    "customer_note": "The zip broke on first use."  }}
GET
/returns/{return}

Requires scope merchant-returns-read.

Retrieves one return. {return} is a p_id or UUID of this store; another store’s return, a return of an order the caller may not read and an unknown reference all answer 404. A return is requested until the store approves it (open), declines it (declined) or cancels it (cancelled); an open return is closed when the store is done with it or cancelled; declined and cancelled are final, and a closed return can be reopened (POST returns/{return}/reopen). line_items[].quantity is what comes back, received_quantity what the store has taken in and restocked_quantity what went back on the shelf. A return holds no money: a refund is made on the order. customer_note is present only with merchant-customers-contact-read; the store’s own note is never returned to a key or an app.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

return*string

Identifier of the return, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/returns/1001" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Return retrieved.",  "data": {    "id": 1001,    "status": "open",    "source": "api",    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "received_quantity": 1,        "restocked_quantity": 1,        "reason": "defective"      }    ],    "decline_reason": null,    "customer_message": "Send it back to our New York shop; we will refund you when it arrives.",    "requested_at": "2026-10-02T10:20:00+01:00",    "opened_at": "2026-10-02T11:05:00+01:00",    "reopened_at": null,    "declined_at": null,    "closed_at": null,    "cancelled_at": null,    "refunded": false,    "refunded_amount": "0.00",    "currency": "USD",    "created_at": "2026-10-02T10:20:00+01:00",    "updated_at": "2026-10-05T15:30:00+01:00",    "customer_note": "The zip broke on first use."  }}
GET
/orders/{order}/returnable

Requires scope merchant-returns-read.

Answers, for each line of an order, how many units can still be returned: the units ordered, less what a requested or open return already asks for and what a closed return received (declined and cancelled returns count nothing). returnable is false, with the reason, for an order that was not yet delivered or completed and for one cancelled or rejected; a return can be recorded on an order only while it is true. {order} is a p_id or UUID of this store; another store’s order, an unplaced checkout and an unknown reference answer 404. Read this before POST returns to choose each line’s order_item and the most it can take.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

order*string

Identifier of the order, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/orders/58213/returnable" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Returnable quantities retrieved.",  "data": {    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "returnable": true,    "reason": null,    "reason_code": null,    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "returnable_quantity": 1      }    ]  }}
POST
/returns/{return}/approve

Requires scope merchant-returns-update.

Accepts a requested return: its status becomes open and goods can be received against it. customer_message (optional, up to 1000 characters) is what the store tells the customer; it is kept on the return and, when the customer asked for the return online, emailed to them. A return in any other status answers 409 return_transition_invalid (a closed return is reopened, not approved). {return} is a p_id or UUID of this store; another store’s return reads as not found. Answers the return. Fires returns/update.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

return*string

Identifier of the return, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST returns/{return}/approve: the update permission, then an optional message for the customer.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/returns/1001/approve" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "customer_message": "Send it back to our New York shop; we will refund you when it arrives."  }'
{  "status": "success",  "message": "Return approved.",  "data": {    "id": 1001,    "status": "open",    "source": "api",    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "received_quantity": 0,        "restocked_quantity": 0,        "reason": "defective"      }    ],    "decline_reason": null,    "customer_message": "Send it back to our New York shop; we will refund you when it arrives.",    "requested_at": "2026-10-02T10:20:00+01:00",    "opened_at": "2026-10-02T11:05:00+01:00",    "reopened_at": null,    "declined_at": null,    "closed_at": null,    "cancelled_at": null,    "refunded": false,    "refunded_amount": "0.00",    "currency": "USD",    "created_at": "2026-10-02T10:20:00+01:00",    "updated_at": "2026-10-02T11:05:00+01:00",    "customer_note": "The zip broke on first use."  }}
POST
/returns/{return}/decline

Requires scope merchant-returns-update.

Refuses a requested return: its status becomes declined (final) and its units are free to be requested again. reason (up to 500 characters) is kept as decline_reason, the store’s own record. customer_message (optional, up to 1000 characters) is what the store tells the customer; it is kept on the return and, when the customer asked for the return online, emailed to them. A return in any other status answers 409 return_transition_invalid. {return} is a p_id or UUID of this store; another store’s return reads as not found. Answers the return. Fires returns/update.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

return*string

Identifier of the return, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST returns/{return}/decline: the update permission, then an optional reason and an optional message for the customer.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/returns/1001/decline" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "reason": "Outside the 14-day window.",    "customer_message": "Sorry, this order is past our 14-day return window."  }'
{  "status": "success",  "message": "Return declined.",  "data": {    "id": 1001,    "status": "declined",    "source": "api",    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "received_quantity": 0,        "restocked_quantity": 0,        "reason": "defective"      }    ],    "decline_reason": "Outside the 14-day window.",    "customer_message": "Sorry, this order is past our 14-day return window.",    "requested_at": "2026-10-02T10:20:00+01:00",    "opened_at": null,    "reopened_at": null,    "declined_at": "2026-10-02T11:05:00+01:00",    "closed_at": null,    "cancelled_at": null,    "refunded": false,    "refunded_amount": "0.00",    "currency": "USD",    "created_at": "2026-10-02T10:20:00+01:00",    "updated_at": "2026-10-02T11:05:00+01:00",    "customer_note": "The zip broke on first use."  }}
POST
/returns/{return}/cancel

Requires scope merchant-returns-update.

Cancels a requested or open return that has received nothing: its status becomes cancelled (final) and its units are free to be requested again. Send no body. A declined, cancelled or closed return answers 409 return_transition_invalid, and so does a return that already received units: its counts and its effect on the shelf stay true, so close it instead (POST returns/{return}/close). {return} is a p_id or UUID of this store; another store’s return reads as not found. Answers the return. Fires returns/update.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

return*string

Identifier of the return, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/returns/1001/cancel" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Return cancelled.",  "data": {    "id": 1001,    "status": "cancelled",    "source": "api",    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "received_quantity": 0,        "restocked_quantity": 0,        "reason": "defective"      }    ],    "decline_reason": null,    "customer_message": null,    "requested_at": "2026-10-02T10:20:00+01:00",    "opened_at": null,    "reopened_at": null,    "declined_at": null,    "closed_at": null,    "cancelled_at": "2026-10-02T12:00:00+01:00",    "refunded": false,    "refunded_amount": "0.00",    "currency": "USD",    "created_at": "2026-10-02T10:20:00+01:00",    "updated_at": "2026-10-02T11:05:00+01:00",    "customer_note": "The zip broke on first use."  }}
POST
/returns/{return}/close

Requires scope merchant-returns-update.

Closes an open return the store is done with: its status becomes closed, nothing more can be received against it, and the units it did not receive are free to be requested again. What was received stays received and stays on the shelf. A closed return can be reopened (POST returns/{return}/reopen). Send no body. A return in any other status answers 409 return_transition_invalid. {return} is a p_id or UUID of this store; another store’s return reads as not found. Answers the return. Fires returns/update.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

return*string

Identifier of the return, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/returns/1001/close" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Return closed.",  "data": {    "id": 1001,    "status": "closed",    "source": "api",    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "received_quantity": 2,        "restocked_quantity": 2,        "reason": "defective"      }    ],    "decline_reason": null,    "customer_message": "Send it back to our New York shop; we will refund you when it arrives.",    "requested_at": "2026-10-02T10:20:00+01:00",    "opened_at": "2026-10-02T11:05:00+01:00",    "reopened_at": null,    "declined_at": null,    "closed_at": "2026-10-05T15:30:00+01:00",    "cancelled_at": null,    "refunded": false,    "refunded_amount": "0.00",    "currency": "USD",    "created_at": "2026-10-02T10:20:00+01:00",    "updated_at": "2026-10-05T15:30:00+01:00",    "customer_note": "The zip broke on first use."  }}
POST
/returns/{return}/reopen

Requires scope merchant-returns-update.

Reopens a closed return the store closed too soon: its status becomes open again and goods can be received against it. opened_at stays the first approval, reopened_at is stamped and closed_at is null until it is closed again. Send no body. Only a closed return reopens: a declined or cancelled return is final and any other status answers 409 return_transition_invalid, and so does a return whose order was cancelled since or whose unreceived units another return now asks for. {return} is a p_id or UUID of this store; another store’s return reads as not found. Answers the return. Fires returns/update.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

return*string

Identifier of the return, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/returns/1001/reopen" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Return reopened.",  "data": {    "id": 1001,    "status": "open",    "source": "api",    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "received_quantity": 2,        "restocked_quantity": 2,        "reason": "defective"      }    ],    "decline_reason": null,    "customer_message": "Send it back to our New York shop; we will refund you when it arrives.",    "requested_at": "2026-10-02T10:20:00+01:00",    "opened_at": "2026-10-02T11:05:00+01:00",    "reopened_at": "2026-10-06T09:10:00+01:00",    "declined_at": null,    "closed_at": null,    "cancelled_at": null,    "refunded": false,    "refunded_amount": "0.00",    "currency": "USD",    "created_at": "2026-10-02T10:20:00+01:00",    "updated_at": "2026-10-05T15:30:00+01:00",    "customer_note": "The zip broke on first use."  }}
POST
/returns/{return}/receive

Requires scope merchant-returns-update.

Takes units of an open return in, in full or in part: each line_items[] (at most 100) names an order_item of this return and the quantity received now, at most what is still to be received on that line (422 return_line_invalid; a line that is not on the return, a repeated line and an empty list answer it too). Received units are put back on the shelf unless restock is false: per line at most the units the shelf is still missing (what the order took, less what earlier returns and refunds already put back), through the same stock path as every other restock, and only for tracked stock that was actually taken (an order whose stock was never committed, an untracked product and a digital product restock 0 and the receive still succeeds). restocked_quantity on the line says how many really went back. A return that is not open answers 409 return_transition_invalid. The return stays open until you close it; receiving moves no money (refund the customer with POST orders/{order}/refunds). Idempotency-Key is required: the same key with the same body returns the first answer instead of receiving the goods twice, the same key with another body is 409 idempotency_key_reuse. {return} is a p_id or UUID of this store; another store’s return reads as not found. Answers the return. Fires returns/update.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

return*string

Identifier of the return, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key*string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Take units of an open return in, and put them back on the shelf unless restock is false. Receiving moves stock, so an Idempotency-Key header is REQUIRED on the Merchant API: a retry with the same key and body replays the first answer instead of receiving the goods twice, and the same key with another body is 409 idempotency_key_reuse.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/returns/1001/receive" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "quantity": 1      }    ],    "restock": true  }'
{  "status": "success",  "message": "Return received.",  "data": {    "id": 1001,    "status": "open",    "source": "api",    "order": {      "id": 58213,      "order_number": "26-0924-58213"    },    "line_items": [      {        "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "title": "Smokehouse Party Pack",        "variant_title": null,        "quantity": 2,        "received_quantity": 1,        "restocked_quantity": 1,        "reason": "defective"      }    ],    "decline_reason": null,    "customer_message": "Send it back to our New York shop; we will refund you when it arrives.",    "requested_at": "2026-10-02T10:20:00+01:00",    "opened_at": "2026-10-02T11:05:00+01:00",    "reopened_at": null,    "declined_at": null,    "closed_at": null,    "cancelled_at": null,    "refunded": false,    "refunded_amount": "0.00",    "currency": "USD",    "created_at": "2026-10-02T10:20:00+01:00",    "updated_at": "2026-10-05T15:30:00+01:00",    "customer_note": "The zip broke on first use."  }}