Read and update stock

01Read stock

GET /api/public/v1/stock needs api:read. A retailer reads its own rows at active, unsuppressed locations. A brand reads its own products across active retailer relationships. Use limit and cursor as on every list.

Shell · TEST

curl "https://api.test.stockisto.com/api/public/v1/stock?limit=200" \
  -H "Authorization: Bearer $STOCKISTO_API_KEY"

The 200 response contains data and nextCursor. Each row includes stockId, locationId, skuId, status, quantity, evidence, lastVerifiedAt and lastVerifiedAtLabel. Price freshness uses the separate priceUpdatedAt.

02Update one row

PATCH /api/public/v1/stock/{stockId} needs a retailer key with api:write. Set STOCK_ID to a row from your stock read. Omitted or null fields stay unchanged; v1 cannot clear a value. A 200 response returns the updated stock row.

Shell · TEST

curl -X PATCH "https://api.test.stockisto.com/api/public/v1/stock/$STOCK_ID" \
  -H "Authorization: Bearer $STOCKISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "inStock", "quantity": 4 }'

Field	Value
`status`	`inStock`, `lowStock`, `outOfStock`, `carriesTheLine`, `orderable`
`quantity`	Units on hand, 0 or more.
`isOnDisplayInShowroom`	true or false.
`retailPrice`, `priceCurrency`	Your price and currency.
`promoText`	A short offer line.

03Update many rows

POST /api/public/v1/stock:batch takes 1 to 500 rows, addressed by locationId and skuId. Replace LOCATION_ID and SKU_ID with your own values. A new row needs status and a product from a connected supplier. Set BATCH_KEY to a unique value for this batch.

Shell · TEST

curl -X POST "https://api.test.stockisto.com/api/public/v1/stock:batch" \
  -H "Authorization: Bearer $STOCKISTO_API_KEY" \
  -H "Idempotency-Key: $BATCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rows": [ { "locationId": "LOCATION_ID", "skuId": "SKU_ID", "status": "inStock" } ] }'

A 200 response contains results, created, updated and failed. Each result echoes index, locationId, skuId, action, stockId and error. Actions are created, updated or failed. Check every row even when HTTP status is 200.

04Send it twice safely

Batch writes accept Idempotency-Key. The same key and body within 24 hours replay the first response with Idempotency-Replay: true. A different body with that key returns 409. PATCH sets the supplied values again; it does not store an idempotency response.

05What a write changes

A status or quantity observation stamps the API source and observation time. Price-only changes preserve stock age. Successful writes feed stock.updated webhooks. A brand key cannot write retailer stock: PATCH returns 404; batch rows fail.

Error code	Meaning
`invalid_status`	Use one of the five status values.
`negative_quantity`, `negative_price`	Use a number of 0 or more.
`invalid_price`, `invalid_currency`	Use a price below 100 000 000 and a supported currency.
`location_not_found`, `sku_not_available`	Use a location you own and a product you can write.
`status_required_for_create`	Supply a status for a new row.
`duplicate_row_in_batch`	Send each location and product pair once.
`retailer_key_required_for_stock_write`	Use the retailer’s key.

Authentication, errors and pagination