curl --request POST \
  --url https://api.arcuserp.com/v1/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "original_order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reason": "wrong_item",
  "refund_amount": 150,
  "items": [
    {
      "order_item_id": "11111111-2222-3333-4444-555555555555",
      "quantity": 1,
      "condition": "unused"
    }
  ],
  "restocking_fee": {
    "type": "percentage",
    "value": 10
  },
  "auto_refund": true,
  "refund_payment_id": "22222222-3333-4444-5555-666666666666"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "return",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "return_number": "<string>",
  "original_order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_rma_number": "<string>",
  "inspection_required": true,
  "restocking_fee": 123,
  "refund_amount": 123,
  "return_to_vendor": true,
  "notes": "<string>",
  "metadata": {},
  "received_at": "2023-11-07T05:31:56Z",
  "closed_at": "2023-11-07T05:31:56Z",
  "cancelled_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Returns

Create a new RMA (status=authorized)

Required API key scope: returns:write

Create a return merchandise authorization (RMA). Atomic-create: a single POST can create the RMA, add inline items[], auto-calculate restocking fees, and issue a refund (auto_refund: true) in one transactional call.

Inline items: pass items[] with order_item_id + quantity to add return line items atomically with the RMA. The quantity field is accepted as an alias for quantity_authorized. Items are inserted before the response is returned; the response includes items[] hydrated inline.

Restocking fee: accepts a flat number (restocking_fee: 25.00) or an object:

{ "type": "percentage", "value": 10 } — 10% of refund_amount
{ "type": "flat", "value": 30.00 } — flat $30.00

Auto-refund: include auto_refund: true + refund_payment_id to issue the refund immediately after RMA creation. Requires returns:write + payments:write scopes. The response includes a refund object if auto_refund succeeded.

Return window: if entities.settings.return_window_days is configured, returns outside the window are rejected with 422 outside_return_window. Pass override_window: true to bypass.

Guide: https://arcuserp.mintlify.app/guides/fulfillment-and-returns

POST

returns

curl --request POST \
  --url https://api.arcuserp.com/v1/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "original_order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reason": "wrong_item",
  "refund_amount": 150,
  "items": [
    {
      "order_item_id": "11111111-2222-3333-4444-555555555555",
      "quantity": 1,
      "condition": "unused"
    }
  ],
  "restocking_fee": {
    "type": "percentage",
    "value": 10
  },
  "auto_refund": true,
  "refund_payment_id": "22222222-3333-4444-5555-666666666666"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "return",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "return_number": "<string>",
  "original_order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_rma_number": "<string>",
  "inspection_required": true,
  "restocking_fee": 123,
  "refund_amount": 123,
  "return_to_vendor": true,
  "notes": "<string>",
  "metadata": {},
  "received_at": "2023-11-07T05:31:56Z",
  "closed_at": "2023-11-07T05:31:56Z",
  "cancelled_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Authorizations

Authorization

string

header

required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity via Settings > Developers > API Keys.

Headers

Idempotency-Key

string

Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.

Maximum string length: 255

Body

application/json

original_order_id

string<uuid>

The originating sales order. Required unless this is a standalone RMA.

account_id

string<uuid>

Customer account. Derived from the original order when original_order_id is provided.

reason

string

Free-text reason for the return.

refund_amount

number<float>

Total dollar amount to refund before restocking fee deduction.

restocking_fee

Flat number (e.g. 25.00) or object form: { type: 'percentage', value: 10 } or { type: 'flat', value: 30 }.

items

object[]

Inline return line items. Added atomically with the RMA. quantity is accepted as an alias for quantity_authorized.

Show child attributes

auto_refund

boolean

default:false

If true, issue the refund immediately after RMA creation. Requires refund_payment_id and payments:write scope. The response includes a 'refund' object.

refund_payment_id

string<uuid>

Required with auto_refund=true. The original payment to refund against.

refund_method

enum<string>

default:original

Refund routing. 'original' refunds to the original payment method.

Available options:

original,

store_credit,

check,

cash

override_window

boolean

default:false

Bypass the entity's return_window_days check. Requires returns:write.

customer_initiated

boolean

default:false

True when return was initiated via the customer portal.

notes

string

metadata

object

Response

Created RMA (hydrated with items[] and refund if inline operations ran)

RMA (return merchandise authorization). Phase A -- refund_amount is readOnly via PATCH; written only by POST /v1/returns/{id}/refund.

string<uuid>

object

enum<string>

Available options:

return

entity_id

string<uuid>

read-only

return_number

string

read-only

status

enum<string>

read-only

Use action endpoints to transition status; PATCH cannot write status.

Available options:

authorized,

expected,

received,

inspecting,

restocked,

written_off,

closed,

sent_to_vendor,

cancelled

original_order_id

string<uuid>

account_id

string<uuid>

vendor_id

string<uuid> | null

vendor_rma_number

string | null

inspection_required

boolean

restocking_fee

number | null

refund_amount

number | null

read-only

SSOT: written only by POST /v1/returns/{id}/refund (refundReturn canonical). PATCH cannot write this field.

return_to_vendor

boolean

source

enum<string> | null

Available options:

csr,

customer_portal,

marketplace

notes

string | null

metadata

object | null

received_at

string<date-time> | null

read-only

closed_at

string<date-time> | null

read-only

cancelled_at

string<date-time> | null

read-only

created_at

string<date-time>

read-only

updated_at

string<date-time>

read-only

List RMAs (return merchandise authorizations)Retrieve a single RMA