Receive inventory (non-PO) -- single or multi-item atomic

ATOMIC-CREATE (2026-05-12): accepts items[] for multi-line atomic receipts OR top-level product_id/quantity/unit_cost for single-item compat mode. All items receive in one DB transaction; any failure rolls back all items. Hard-blocks zero-cost (unit_cost must be > 0 per item). GL: DR Inventory / CR GRNI via postInventoryReceived, fires per item in same transaction (Rule 21). Connector: triggers async pushInventoryToMarketplaces (Shopify/Amazon/eBay). For PO-linked receipts: POST /v1/purchase-orders/{id}/receive. Response: {object:inventory_receive_result, items:[{balance,transaction}], summary} for items[]; single object for compat mode.

POST /inventory/receive

cURL

multi_item

curl --request POST \
  --url https://api.arcuserp.com/v1/inventory/receive \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "location_id": "91aa7588-4dc7-4edd-b172-7de91f5e1f78",
  "notes": "Restocking run from supplier",
  "items": [
    {
      "product_id": "7f6f3e14-eaad-4c45-b922-209f6dc6d140",
      "quantity": 10,
      "unit_cost": 12.5,
      "notes": "Circuit Breaker 10A White"
    },
    {
      "product_id": "ec9288c3-12b1-474f-bb09-b0b15bb7a8ff",
      "quantity": 5,
      "unit_cost": 8.75,
      "notes": "Square D Breaker Black"
    }
  ]
}
'

201

{
  "object": "inventory_receive_result",
  "items": [
    {
      "index": 0,
      "product_id": "7f6f3e14-eaad-4c45-b922-209f6dc6d140",
      "location_id": "91aa7588-4dc7-4edd-b172-7de91f5e1f78",
      "quantity": 10,
      "unit_cost": 12.5,
      "balance": {
        "id": "0118ff93-8f65-4a72-ae7e-ca2a75526631",
        "on_hand": 10,
        "allocated": 0,
        "available": 10,
        "total_value": "125.00",
        "avg_unit_value": "12.5000"
      },
      "transaction": {
        "id": "3096987e-b156-4ee0-b373-8056f5bd8d91",
        "type": "receiving",
        "quantity": 10,
        "unit_price": "12.5000",
        "total_price": "125.00",
        "transaction_id": "IVT-0000153"
      }
    },
    {
      "index": 1,
      "product_id": "ec9288c3-12b1-474f-bb09-b0b15bb7a8ff",
      "location_id": "91aa7588-4dc7-4edd-b172-7de91f5e1f78",
      "quantity": 5,
      "unit_cost": 8.75,
      "balance": {
        "id": "6e082a9d-7314-4bd9-9bf3-609b3aae12b3",
        "on_hand": 5,
        "allocated": 0,
        "available": 5,
        "total_value": "43.75",
        "avg_unit_value": "8.7500"
      },
      "transaction": {
        "id": "f7d36a63-008b-4973-9025-e22328786e40",
        "type": "receiving",
        "quantity": 5,
        "unit_price": "8.7500",
        "total_price": "43.75",
        "transaction_id": "IVT-0000154"
      }
    }
  ],
  "summary": {
    "total_items": 2,
    "total_quantity": 15
  }
}

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

Option 1

Option 2

Multi-item atomic mode

location_id · string<uuid> · required

Layer 4 -- required

items · object[] · required

Minimum array length: 1

Show child attributes

notes · string

Response

201

application/json

Inventory received

object · enum<string>

Available options: inventory_receive_result