Adjust inventory -- single or multi-item atomic (cycle count, shrinkage, revaluation)

ATOMIC-CREATE (2026-05-12): accepts items[] for multi-line atomic adjustments OR top-level product_id/quantity for single-item compat mode. All items adjust in one DB transaction; any failure rolls back all items (no partial writes). Positive or negative delta per item. Hard-blocks negative balance and zero-cost positives. GL: DR/CR Inventory + DR/CR Suspense or Shrinkage via glPostInventoryAdjustment, fires per item in same transaction (Rule 21). Connector: triggers async pushInventoryToMarketplaces. Response: {object:inventory_adjustment_result, items:[{index,product_id,balance,transaction,gl_amount,journal_entry_id,consumed_layers}], summary} for items[]; single object for compat mode. On failure: {error, code, hint, items_completed_before_failure} -- all items rolled back regardless of items_completed_before_failure. migration:write scope: documents authorization for opening-balance loads. Hard-blocks still apply.

POST /inventory/adjustments

cURL

cycle_count_multi

curl --request POST \
  --url https://api.arcuserp.com/v1/inventory/adjustments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "location_id": "91aa7588-4dc7-4edd-b172-7de91f5e1f78",
  "reason": "cycle_count",
  "memo": "Monthly cycle count Q2 2026",
  "items": [
    {
      "product_id": "7f6f3e14-eaad-4c45-b922-209f6dc6d140",
      "quantity_delta": 3,
      "unit_cost": 12.5,
      "notes": "Count correction -- physical count higher than system"
    },
    {
      "product_id": "ec9288c3-12b1-474f-bb09-b0b15bb7a8ff",
      "quantity_delta": -2,
      "notes": "Shrinkage discovered during count"
    }
  ]
}
'

201

{
  "object": "inventory_adjustment_result",
  "items": [
    {
      "index": 0,
      "product_id": "7f6f3e14-eaad-4c45-b922-209f6dc6d140",
      "location_id": "91aa7588-4dc7-4edd-b172-7de91f5e1f78",
      "quantity_delta": 3,
      "gl_amount": 37.5,
      "journal_entry_id": "c79ab8cf-b840-471f-bea9-6a24df80f550",
      "balance": {
        "on_hand": 13,
        "allocated": 0,
        "available": 13,
        "total_value": "162.50"
      },
      "transaction": {
        "id": "10e06976-8096-48bc-bbbd-5fe71626f544",
        "type": "adjustment",
        "quantity": 3,
        "unit_price": "12.5000",
        "total_price": "37.50",
        "transaction_id": "IVT-0000155"
      },
      "consumed_layers": []
    },
    {
      "index": 1,
      "product_id": "ec9288c3-12b1-474f-bb09-b0b15bb7a8ff",
      "location_id": "91aa7588-4dc7-4edd-b172-7de91f5e1f78",
      "quantity_delta": -2,
      "gl_amount": -17.5,
      "journal_entry_id": "a8c5c8c6-b0b0-4e63-918d-a247189735f3",
      "balance": {
        "on_hand": 3,
        "allocated": 0,
        "available": 3,
        "total_value": "26.25"
      },
      "transaction": {
        "id": "93659e88-f3ba-4709-9798-388886820ea0",
        "type": "adjustment",
        "quantity": -2,
        "unit_price": "8.7500",
        "total_price": "17.50",
        "transaction_id": "IVT-0000156"
      },
      "consumed_layers": [
        {
          "layer_id": "3de7680e-fba2-444a-a204-7290cc6f08e1",
          "qty_used": 2,
          "qty_after": 3,
          "unit_cost": 8.75,
          "layer_cogs": 17.5
        }
      ]
    }
  ],
  "summary": {
    "total_items": 2,
    "total_gl_impact": 20
  }
}

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

reason · string

Response

201

application/json

Adjustment applied

object · enum<string>

Available options: inventory_adjustment_result