Skip to main content
Synq tracks stock using an inventory ledger — a permanent, append-only record of every movement that has ever touched a SKU. Each time you receive new stock, write off shrinkage, or make a manual correction, Synq records the variant, location, quantity change, and the reason. The current on-hand quantity for any variant at any location is always derived from the sum of those recorded movements. This design gives you a complete, auditable history of your inventory without ever overwriting past data.

​
How inventory adjustments work

When you post an adjustment, Synq permanently records a stock movement with the following fields:
  • variant_id — the product variant the movement applies to
  • location_id — the warehouse or fulfillment center where stock changed
  • quantity_delta — a signed integer: positive values add stock, negative values remove it
Each adjustment is written permanently and cannot be modified or deleted.
Inventory adjustments are permanent. Once a movement is recorded, it cannot be modified or deleted. To correct a mistake, post a new adjustment that reverses the error.

​
Required headers

Every request to the Synq API requires three headers for tenant isolation and authentication.
HeaderDescription
AuthorizationBearer <your_api_token>
X-Tenant-IDYour Synq tenant identifier
X-Org-IDThe organization scope for the request

​
Adjust inventory

Use POST /api/v1/inventory/adjust to record any stock movement for a variant at a specific location. This single endpoint covers all use cases: receiving new goods, removing damaged units, correcting miscounts, and writing off shrinkage.

​
Endpoint

POST /api/v1/inventory/adjust

​
Request fields

​
variant_id
string (UUID)
required
The Synq variant UUID for the SKU whose stock you are adjusting.
​
location_id
string (UUID)
required
The UUID of the warehouse or fulfillment location where stock is changing.
​
quantity_delta
integer
required
The signed quantity to apply. Use a positive integer to add stock (e.g. receiving a shipment), and a negative integer to remove stock (e.g. shrinkage or a manual write-off).
Use location_id to track stock independently per warehouse, retail store, or 3PL fulfillment centre. Synq computes available stock per variant_id + location_id pair, so you always know exactly how much stock is available at each site — not just globally.

​
Examples

curl -X POST https://api.synq.io/api/v1/inventory/adjust \
  -H "Authorization: Bearer $SYNQ_API_TOKEN" \
  -H "X-Tenant-ID: $SYNQ_TENANT_ID" \
  -H "X-Org-ID: $SYNQ_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "location_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "quantity_delta": 50
  }'

​
Response

A successful adjustment returns 200 OK with the details of the recorded stock movement.
Response
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "org_id": "c2d3e4f5-a6b7-8901-bcde-f12345678901",
  "tenant_id": "d3e4f5a6-b7c8-9012-cdef-123456789012",
  "variant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "location_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "transaction_type": "adjustment",
  "quantity_delta": 50,
  "reference_id": null,
  "unit_cost": null,
  "notes": "API Adjustment",
  "created_at": "2025-06-01T11:45:00Z"
}

​
Response fields

​
id
string (UUID)
The unique identifier of this recorded stock movement.
​
org_id
string (UUID)
The organization this adjustment belongs to.
​
tenant_id
string (UUID)
The tenant this adjustment belongs to.
​
variant_id
string (UUID)
The variant whose stock was adjusted.
​
location_id
string (UUID)
The location where the stock movement occurred.
​
transaction_type
string
The type of movement recorded. API-driven adjustments use "adjustment". Order fulfillment and returns use their own transaction types written automatically by the OMS.
​
quantity_delta
integer
The signed delta recorded for this movement. Positive means stock was added; negative means stock was removed.
​
reference_id
string | null
An optional reference identifier linking this movement to an external record (e.g. a purchase order number). null for generic API adjustments.
​
unit_cost
number | null
Cost per unit at the time of the movement, if captured. null for generic API adjustments.
​
notes
string
Human-readable note attached to this movement. Defaults to "API Adjustment" for entries created via this endpoint.
​
created_at
string (ISO 8601)
UTC timestamp of when this stock movement was recorded.

​
Common use cases

Scenarioquantity_deltaNotes
Receiving a purchase order+NPost one adjustment per variant per location in the PO
Manual stocktake correction+N or -NDelta = physical count minus current on-hand total
Shrinkage / damage write-off-NRecord loss; cannot be undone, only reversed
Return restocking+NAdd units back after a return is inspected and accepted
Do not use this endpoint to reflect inventory consumed by order fulfillment. The Synq OMS automatically reserves and deducts inventory when it processes an order. Manually posting a negative delta on top of a fulfilled order will result in double-deduction.