Inventory API

Keep inventory synchronized

Populate opening records from a controlled snapshot, then send each receipt, move, and correction as an idempotent ledger change.

INVENTORY API

Choose an environment #

Production  https://api.inventory.velosity.one
Test        https://api.inventory.test.velosity.one

Send the API key in X-APIKEY. Every inventory write and import also requires an Idempotency-Key. Derive it from a stable source transaction or import-run ID and reuse it when retrying the same operation.

Inventory is an append-only ledger. A balance is the sum of its quantity changes. Opening records add the first entries; later requests add movements and corrections. They do not replace a stored balance.

01 / INITIAL POPULATION

Load locations, then opening balances #

Create inventory-enabled items before loading quantities.
Validate locations with POST /v1/inventory/locations/import?dryRun=true, then repeat without dryRun.
Take an ERP snapshot at a recorded UTC cutoff and create a CSV with Number, Location, and Quantity.
Validate it with POST /v1/inventory/import?dryRun=true, then submit the unchanged file without dryRun under a new idempotency key.
Reconcile every item/location pair before enabling incremental updates.

curl --request POST "https://api.inventory.velosity.one/v1/inventory/import" \
  --header "X-APIKEY: YOUR_API_KEY" \
  --header "Idempotency-Key: erp-opening-2026-10-07" \
  --form "importfile=@opening-balances.csv;type=text/csv"

The import is atomic and accepts at most 10,000 data rows or 10 MiB. Each row creates an INITIAL ledger entry. Split larger loads into deterministic batches with a stable key for each batch.

Opening imports are additive. Submitting the same balances with a different idempotency key adds them again. Record the completed import ID and do not use this endpoint for periodic balance refreshes.

02 / ONGOING UPDATES

Record the business event #

Operation	Endpoint	Effect
Receive	`PUT /v1/inventory/receive`	Adds a positive whole-number quantity.
Move	`PUT /v1/inventory/move`	Subtracts from the source and adds to the destination atomically.
Correct or count	`PUT /v1/inventory`	Adds a signed `QuantityChange`. A negative change cannot make on-hand inventory negative.

For a correction, send ItemID, LocationID, QuantityChange, ReferenceType, ReferenceID, and ReferenceLineNumber. Use ADJUSTMENT, COUNT, or REVERSAL as appropriate and retain the source document identity.

Retry an unchanged source event with the same idempotency key. A reused key with different data returns a conflict; a new key represents a new business event.

03 / RECONCILIATION

Convert snapshots into differences #

When an ERP publishes absolute balances, read Velosity with GET /v1/inventory/status/all or GET /v1/inventory/status/locations/{locationId}. Post only the difference as a correction.

Velosity balance: 85
ERP snapshot:     92
QuantityChange:   +7

Process events for each item and location in source order. Monitor unmapped records, failed writes, quantity variance, and synchronization lag.

Open Inventory API reference