Skip to main content
POST
/
inventory
/
opening-stock
curl --request POST \
  --url https://api.arcuserp.com/v1/inventory/opening-stock \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "7f6f3e14-eaad-4c45-b922-209f6dc6d140",
  "location_id": "91aa7588-4dc7-4edd-b172-7de91f5e1f78",
  "target_on_hand": 144,
  "unit_cost": 44,
  "external_id": "VERSA-SNAPSHOT-99127",
  "notes": "Opening stock from Versa snapshot (Dayton facility)"
}
'
{
  "object": "inventory_opening_stock_result",
  "action": "noop",
  "idempotent": true,
  "balance": {},
  "transaction": {},
  "fifo_layer": {}
}
{
  "object": "inventory_opening_stock_result",
  "idempotent": true,
  "balance": {},
  "transaction": {},
  "fifo_layer": {}
}
{
  "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": "opening_stock_already_consumed",
  "code": "opening_stock_already_consumed",
  "hint": "<string>",
  "consumed_qty": 123,
  "opening_qty": 123
}

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
​
product_id
string<uuid>
required

Arcus product UUID.

​
location_id
string<uuid>
required

Arcus location UUID.

​
target_on_hand
integer
required

The TARGET on-hand value (not a delta). setOpeningStock writes inventory_balances.on_hand = target_on_hand directly.

Required range: x >= 0
​
variant_id
string<uuid> | null

Optional product_variants UUID; null for non-variant products.

​
unit_cost
number<float>

Per-unit cost. Required when target_on_hand > 0; ignored when target_on_hand = 0. setOpeningStock refuses positive opening qty without a positive unit_cost (would corrupt FIFO + GL opening Inventory Asset balance).

Required range: x >= 0.0001
​
external_id
string

Optional source-system row identifier (e.g., Versa snapshot id). Stored on inventory_transactions.reference_number for audit traceability. Idempotency keys on (entity, product, location, reference_type='opening_balance'), NOT on external_id; external_id is informational only.

Maximum string length: 80
​
notes
string

Optional free-text source memo. Stored on inventory_transactions.notes.

Response

Idempotent no-op. A prior opening row exists at this (entity, product, variant, location) with the same target_on_hand and unit_cost. No DB write occurred. Returns the existing balance

  • transaction.
​
object
enum<string>
Available options:
inventory_opening_stock_result
​
action
enum<string>
Available options:
noop
​
idempotent
boolean
​
balance
object
​
transaction
object
​
fifo_layer
object | null