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

full_atomic_create

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"
}
'

201

{
  "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"
}

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 · number<float> object

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

201

application/json

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.

id · 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