Update stock counts

Set counted stock or add and remove units by SKU, safely retried with an idempotency key. Reaches linked marketplace listings.

View as Markdown

Stock is the units on hand (on the shelf). Available is on hand minus what open orders hold: what can still be sold.

  • Connector: preview_stock_change, then apply_stock_change (permission stock:write).
  • API: POST /stock.

Stock changes only through this call, never through the product update.

Count or adjust#

Each row sends one of:

  • value: the units now on the shelf, from a count. 0 or more.
  • delta: units to add (positive) or remove (negative), for example -3 for damaged goods. Not 0.

Optional per row:

  • expected_from (with value only): the on-hand you read before. If it has changed since, the row is refused instead of overwritten. Use it when time passes between reading and writing.
  • reason: up to 200 characters, shown in the shop's stock history, e.g. monthly count.

Request#

{
  "idempotency_key": "count-2026-10-25-sheet1",
  "dry_run": true,
  "items": [
    { "sku": "TM-001", "value": 40, "expected_from": 37, "reason": "monthly count" },
    { "sku": "TM-002", "delta": -3, "reason": "damaged in transit" }
  ]
}

Retrying safely#

Give each new change its own idempotency_key (8–100 characters: letters, digits and . _ : -). If the call times out, send the same request with the same key: rows already applied come back already_applied and are not applied twice. Never reuse a key for a different change: a row with different numbers under a reused key is applied.

Result#

StatusMeaning
would_updatedry run: from, to and available show what would happen
updatedapplied: from (on hand before), to (on hand after), available
already_appliedthis row was already applied under this idempotency key
errornot applied; error says why

A dry run checks each row's shape, that the SKU is on your SellerSideKick store and expected_from. It does not check holds by open orders, a delta on a SKU that was never counted, or a replay, so the real call can still answer some rows with error or already_applied.

  • A delta can't take on hand below what open orders hold. A counted value is recorded as counted, even below that.
  • Only SKUs on your SellerSideKick store: a SKU that is only on a marketplace is an error row and is never sent anywhere.

What reaches the marketplaces#

Stock changes are recorded in the shop's stock history and sent to the SKU's linked Shopee, Lazada and TikTok listings, usually within about 10 minutes.