> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new RMA (status=authorized)

> <Note>Required API key scope: `returns:write`</Note>

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




## OpenAPI

````yaml /openapi.yaml post /returns
openapi: 3.1.0
info:
  title: Arcus ERP Public API
  version: 1.0.0
  description: >
    Arcus ERP public REST API. Designed for external integrations and data
    migration.


    **Authentication.** Bearer token (API key) via the `Authorization` header.

    Format: `Authorization: Bearer ark_live_ent_<code>_<random>` (or
    `ark_test_*` for sandbox).

    API keys are issued per-entity in **Settings > Developers > API Keys**.


    **Entity scoping.** The entity is encoded in the API key prefix; routes are
    flat

    (e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform
    endpoints

    (migration, reconciliation, events, webhook endpoints, API keys) use the

    `/v1/entities/{entity_id}/...` form -- those are noted in their tags.


    **Key capabilities.**
      - Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource).
      - Cursor-based pagination (`starting_after` / `ending_before` / `limit`).
      - Idempotency via the `Idempotency-Key` header.
      - Webhook events for asynchronous notification.
      - Conditional requests / ETag for cache validation.
servers:
  - url: https://api.arcuserp.com/v1
    description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys)
  - url: https://dev-api.arcuserp.com/v1
    description: >-
      Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev
      RDS)
security: []
paths:
  /returns:
    post:
      tags:
        - Returns
      summary: Create a new RMA (status=authorized)
      description: >
        <Note>Required API key scope: `returns:write`</Note>


        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
      operationId: createReturn
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                original_order_id:
                  type: string
                  format: uuid
                  description: >-
                    The originating sales order. Required unless this is a
                    standalone RMA.
                account_id:
                  type: string
                  format: uuid
                  description: >-
                    Customer account. Derived from the original order when
                    original_order_id is provided.
                reason:
                  type: string
                  description: Free-text reason for the return.
                refund_amount:
                  type: number
                  format: float
                  description: >-
                    Total dollar amount to refund before restocking fee
                    deduction.
                restocking_fee:
                  description: >-
                    Flat number (e.g. 25.00) or object form: { type:
                    'percentage', value: 10 } or { type: 'flat', value: 30 }.
                  oneOf:
                    - type: number
                      format: float
                      description: Flat dollar restocking fee.
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - percentage
                            - flat
                          description: Fee calculation method.
                        value:
                          type: number
                          description: Percentage (0-100) or flat dollar amount.
                      required:
                        - type
                        - value
                items:
                  type: array
                  description: >-
                    Inline return line items. Added atomically with the RMA.
                    quantity is accepted as an alias for quantity_authorized.
                  items:
                    type: object
                    properties:
                      order_item_id:
                        type: string
                        format: uuid
                        description: >-
                          Links to the originating order line. Enables FIFO cost
                          capture for GL reversal.
                      product_id:
                        type: string
                        format: uuid
                        description: Required if order_item_id not provided.
                      quantity:
                        type: integer
                        minimum: 1
                        description: Alias for quantity_authorized.
                      quantity_authorized:
                        type: integer
                        minimum: 1
                        description: Number of units authorized for return.
                      condition:
                        type: string
                        enum:
                          - new
                          - used
                          - damaged
                          - defective
                        description: Physical condition of the returned item.
                      reason_code:
                        type: string
                        enum:
                          - defective
                          - damaged_in_transit
                          - wrong_item_shipped
                          - not_as_described
                          - no_longer_needed
                          - found_better_price
                          - arrived_late
                          - other
                          - unspecified
                        description: >-
                          Per-line return reason. Powers returns-by-reason
                          analytics (R31). Defaults to 'unspecified' if omitted.
                      notes:
                        type: string
                auto_refund:
                  type: boolean
                  default: false
                  description: >-
                    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:
                  type: string
                  format: uuid
                  description: >-
                    Required with auto_refund=true. The original payment to
                    refund against.
                refund_method:
                  type: string
                  enum:
                    - original
                    - store_credit
                    - check
                    - cash
                  default: original
                  description: >-
                    Refund routing. 'original' refunds to the original payment
                    method.
                override_window:
                  type: boolean
                  default: false
                  description: >-
                    Bypass the entity's return_window_days check. Requires
                    returns:write.
                customer_initiated:
                  type: boolean
                  default: false
                  description: True when return was initiated via the customer portal.
                notes:
                  type: string
                metadata:
                  type: object
            examples:
              full_atomic_create:
                summary: RMA + items + percentage restocking fee + auto-refund
                value:
                  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
              rma_only:
                summary: Bare RMA without items or refund
                value:
                  original_order_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  reason: damaged_in_transit
                  refund_amount: 75
      responses:
        '201':
          description: >-
            Created RMA (hydrated with items[] and refund if inline operations
            ran)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Return'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        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.
      schema:
        type: string
        maxLength: 255
  schemas:
    Return:
      type: object
      description: >-
        RMA (return merchandise authorization). Phase A -- refund_amount is
        readOnly via PATCH; written only by POST /v1/returns/{id}/refund.
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
          enum:
            - return
        entity_id:
          type: string
          format: uuid
          readOnly: true
        return_number:
          type: string
          readOnly: true
        status:
          type: string
          enum:
            - authorized
            - expected
            - received
            - inspecting
            - restocked
            - written_off
            - closed
            - sent_to_vendor
            - cancelled
          readOnly: true
          description: >-
            Use action endpoints to transition status; PATCH cannot write
            status.
        original_order_id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        vendor_id:
          type: string
          format: uuid
          nullable: true
        vendor_rma_number:
          type: string
          nullable: true
        inspection_required:
          type: boolean
        restocking_fee:
          type: number
          nullable: true
        refund_amount:
          type: number
          nullable: true
          readOnly: true
          description: >-
            SSOT: written only by POST /v1/returns/{id}/refund (refundReturn
            canonical). PATCH cannot write this field.
        return_to_vendor:
          type: boolean
        source:
          type: string
          enum:
            - csr
            - customer_portal
            - marketplace
          nullable: true
        notes:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
        received_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        closed_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        cancelled_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    ErrorEnvelope:
      type: object
      description: |
        Canonical error response envelope. All API errors use this shape.
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Machine-readable error key
          example: not_found
        code:
          type: string
          description: Machine-readable error code (often same as error)
          example: not_found
        type:
          type: string
          enum:
            - validation_error
            - permission_error
            - not_found
            - conflict
            - rate_limit
            - internal
            - expand_error
            - not_implemented
          example: not_found
        hint:
          type: string
          description: Human-readable one-sentence explanation (English)
          example: >-
            The requested order does not exist or does not belong to this
            entity.
        param:
          type: string
          description: The parameter that caused the error, if applicable
          example: expand[0]
        required:
          type: string
          description: The scope required (only on insufficient_scope errors)
          example: accounts:read
        request_id:
          type: string
          description: >-
            Unique request ID for support tracing (maps to CloudWatch log
            stream)
          example: req_abc123
  responses:
    Error:
      description: Error response (400/401/403/404/409/422/429/500)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        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_<code>_<random>
        Test keys use ark_test_ent_<code>_<random>. Both are issued per entity
        via Settings > Developers > API Keys.

````