Stock
Stock of a variant at a location: read the levels, set the on-hand quantity after a count, receive or write off goods.
Stock
Objects
InventoryLevel
variant_idintegerrequiredID of the variant. Together with location_id it identifies the stock level; a pair missing from the list has zero stock.
location_idintegerrequiredID of the store location.
on_handstringrequiredPhysical stock at the location across all its bins, a decimal string in the unit of the variant. Setting stock names and checks this value.
reservedstringrequiredQuantity reserved for orders, a decimal string in the unit of the variant.
availablestringrequiredQuantity that can be sold: stock that can be picked minus reservations, a decimal string. Negative when more was sold than there was.
updated_atstring (date-time) or nullrequiredWhen the stock level last changed; null when the pair has had no stock movements yet.
InventoryChange
statusstringrequiredOutcome of the write: applied — the stock changed; unchanged — the stock already had this value; pending_approval — the write-off waits for approval in the store: on_hand has not changed yet, available already excludes the held quantity.
- Values:
appliedunchangedpending_approval
Stock level of the pair after the write.
Endpoints
List stock levels by location changed since a given time
get/inventory-levels
Scope: inventory:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
variant_idintegerOnly stock of this variant.
- Minimum:
- 1
location_idintegerOnly stock at this location.
- Minimum:
- 1
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/inventory-levels" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"variant_id": 0,
"location_id": 0,
"on_hand": "string",
"reserved": "string",
"available": "string",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Set the on-hand quantity of a variant at a location
post/inventory-levels/set
Scope: inventory:write
Parameters
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
variant_idintegerrequiredID of the variant. Together with location_id it identifies the stock level; a pair missing from the list has zero stock.
location_idintegerrequiredID of the store location.
commentstring or nullComment of the movement.
- Max length:
- 500
lot_numberstring or nullLot the difference goes to, for a variant tracked by lots.
- Max length:
- 64
expires_atstring (date) or nullExpiry date of a new lot, in the store time zone.
on_handstringrequiredPhysical stock at the location across all its bins, a decimal string in the unit of the variant. Setting stock names and checks this value.
- Max length:
- 32
- Pattern:
^-?\d{1,15}(\.\d{1,15})?$
expected_on_handstringrequiredThe on-hand stock you counted against, a decimal string. If the stock changed since, the request gets 409 stock_on_hand_changed and changes nothing.
- Max length:
- 32
- Pattern:
^-?\d{1,15}(\.\d{1,15})?$
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns InventoryChange
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
stock_held_by_write_offsStock is held by write-offs awaiting approval - 409
stock_on_hand_changedOn-hand quantity changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/inventory-levels/set" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"variant_id": 0,
"location_id": 0,
"comment": "string",
"lot_number": "string",
"expires_at": "2026-01-15",
"on_hand": "string",
"expected_on_hand": "string"
}{
"status": "applied",
"inventory_level": {
"variant_id": 0,
"location_id": 0,
"on_hand": "string",
"reserved": "string",
"available": "string",
"updated_at": "2026-01-15T12:00:00Z"
}
}Receive stock or write it off at a location
post/inventory-levels/adjust
Scope: inventory:write
Parameters
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
variant_idintegerrequiredID of the variant. Together with location_id it identifies the stock level; a pair missing from the list has zero stock.
location_idintegerrequiredID of the store location.
commentstring or nullComment of the movement; required when the write-off reason requires it.
- Max length:
- 500
lot_numberstring or nullFor restock of a variant tracked by lots — the lot; a new lot gets expires_at. Without it the goods go into a new lot with an automatic number, as on receiving.
- Max length:
- 64
expires_atstring (date) or nullExpiry date of a new lot, in the store time zone.
reasonstringrequiredrestock — goods arrive, delta is positive; write_off — goods are written off for a reason of the store (write_off_reason_id), delta is negative.
- Values:
restockwrite_off
deltastringrequiredChange of the on-hand stock, a decimal string in the unit of the variant. Lowering the stock without a write-off reason is not possible: a correction of a wrong count goes through setting the stock.
- Max length:
- 32
- Pattern:
^-?\d{1,15}(\.\d{1,15})?$
write_off_reason_idintegerFor write_off — the reason (/v1/write-off-reasons), which must be selectable.
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns InventoryChange
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/inventory-levels/adjust" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"variant_id": 0,
"location_id": 0,
"comment": "string",
"lot_number": "string",
"expires_at": "2026-01-15",
"reason": "restock",
"delta": "string",
"write_off_reason_id": 0
}{
"status": "applied",
"inventory_level": {
"variant_id": 0,
"location_id": 0,
"on_hand": "string",
"reserved": "string",
"available": "string",
"updated_at": "2026-01-15T12:00:00Z"
}
}