Stock

Stock of a variant at a location: read the levels, set the on-hand quantity after a count, receive or write off goods.

Loading the search index…

Stock

Objects

InventoryLevel

  • variant_idintegerrequired

    ID of the variant. Together with location_id it identifies the stock level; a pair missing from the list has zero stock.

  • location_idintegerrequired

    ID of the store location.

  • on_handstringrequired

    Physical stock at the location across all its bins, a decimal string in the unit of the variant. Setting stock names and checks this value.

  • reservedstringrequired

    Quantity reserved for orders, a decimal string in the unit of the variant.

  • availablestringrequired

    Quantity 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 nullrequired

    When the stock level last changed; null when the pair has had no stock movements yet.

InventoryChange

  • statusstringrequired

    Outcome 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
  • inventory_levelInventoryLevelrequired

    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

  • limitinteger

    Page size: up to 250 records; 50 by default.

    Minimum:
    1
    Maximum:
    250
  • cursorstring

    Opaque 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_deletedboolean

    true — 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_idinteger

    Only stock of this variant.

    Minimum:
    1
  • location_idinteger

    Only stock at this location.

    Minimum:
    1

Responses

200Success

application/json

  • dataarray of InventoryLevelrequired

    Records of the page.

  • deletedarray of objectrequired

    Records erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.

    Fields · 2
    • idintegerrequired

      ID of the erased record.

    • deleted_atstring (date-time)required

      When the record was erased.

  • next_cursorstring or nullrequired

    Cursor of the next page; null on the last page.

  • has_morebooleanrequired

    true when there is a next page.

  • sync_cursorstring or nullrequired

    On 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/inventory-levels" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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-Keystring

    Unique 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_idintegerrequired

    ID of the variant. Together with location_id it identifies the stock level; a pair missing from the list has zero stock.

  • location_idintegerrequired

    ID of the store location.

  • commentstring or null

    Comment of the movement.

    Max length:
    500
  • lot_numberstring or null

    Lot the difference goes to, for a variant tracked by lots.

    Max length:
    64
  • expires_atstring (date) or null

    Expiry date of a new lot, in the store time zone.

  • on_handstringrequired

    Physical 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_handstringrequired

    The 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-Replayedstring

    true 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — 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"
}
Example response · 200
{
  "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-Keystring

    Unique 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_idintegerrequired

    ID of the variant. Together with location_id it identifies the stock level; a pair missing from the list has zero stock.

  • location_idintegerrequired

    ID of the store location.

  • commentstring or null

    Comment of the movement; required when the write-off reason requires it.

    Max length:
    500
  • lot_numberstring or null

    For 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 null

    Expiry date of a new lot, in the store time zone.

  • reasonstringrequired

    restock — 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
  • deltastringrequired

    Change 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_idinteger

    For write_off — the reason (/v1/write-off-reasons), which must be selectable.

Responses

200Success

Headers

  • Idempotent-Replayedstring

    true 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — 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
}
Example response · 200
{
  "status": "applied",
  "inventory_level": {
    "variant_id": 0,
    "location_id": 0,
    "on_hand": "string",
    "reserved": "string",
    "available": "string",
    "updated_at": "2026-01-15T12:00:00Z"
  }
}