Stock API
Only unsold items can be read or changed here. A sold item belongs to its order and is never edited or deleted.
On this page
Stock is encrypted at rest. The list endpoint returns it decrypted, so a key with read_stock holds your unsold inventory.
Editing and deleting share a bucket of 20 requests a minute per key, on top of the overall 60. Their scopes are off on every key until you tick them.
List unsold stock
GET /products/:id/stock
Returns every unsold stock item of a product, oldest first, with its content decrypted.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
variant_id | string | query | Limits the list to one variant. A value that is not a UUID is ignored |
curl -H "Authorization: Bearer YOUR_KEY" \ https://api.shopl.io/api/v1/products/PRODUCT_ID/stock
200 OK { "success": true, "data": { "stock": [ { "id": "9f8e7d6c-2b1a-4c3d-9e8f-7a6b5c4d3e21", "product_id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "variant_id": null, "content": "XXXXX-YYYYY-ZZZZZ", "created_at": "2026-06-20T09:30:00Z" } ], "total": 1 } }
- This list is not paginated. total is the number of items in the array.
- Sold items are never listed. Read what a buyer received from the order.
Add stock
POST /products/:id/stock
Adds stock items to a product. Each string in items becomes one unit a buyer can receive.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
items required | string[] | body | At least one entry. Each entry is stored exactly as sent: not trimmed, not split and not de-duplicated |
variant_id | string | body | Required when the product has variants. Refused when it has none |
notify | boolean | body | Default false. true also refreshes the storefront cache and sends your restock alerts |
{
"items": ["AAAAA-BBBBB-CCCCC", "DDDDD-EEEEE-FFFFF"],
"variant_id": "5d4c3b2a-91f0-4c6d-b7e8-2a1f0c9d8e73",
"notify": true
}curl -X POST \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"items":["AAAAA-BBBBB-CCCCC","DDDDD-EEEEE-FFFFF"]}' \
https://api.shopl.io/api/v1/products/PRODUCT_ID/stock201 Created { "success": true, "data": { "added": 2, "ids": [ "7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d", "1e2f3a4b-5c6d-4e7f-9a8b-7c6d5e4f3a2b" ] } }
- Paid pre-orders waiting on the product are delivered first, oldest first.
- With notify, the restock alerts are a browser push when the product was sold out and a post to your Telegram channel. Each is sent only if you have it switched on.
- A push is all or nothing: on any error no item is added.
Edit a stock item
PATCH /products/:id/stock/:sid
Replaces the content of one unsold stock item. The response never repeats the content.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
sid required | string | path | Stock item id (UUID) |
content required | string | body | Not empty. At most 65,536 bytes |
{ "content": "NEW-CONTENT" }curl -X PATCH \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"content":"NEW-CONTENT"}' \
https://api.shopl.io/api/v1/products/PRODUCT_ID/stock/STOCK_ID200 OK { "success": true, "data": { "id": "9f8e7d6c-2b1a-4c3d-9e8f-7a6b5c4d3e21", "product_id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "variant_id": null, "updated": true } }
- An edit waits up to five seconds for stock pushes, variant creates and other edits on the product, then answers 409. Nothing was written, so retry.
Delete a stock item
DELETE /products/:id/stock/:sid
Permanently removes one unsold stock item. A delete cannot be undone.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
sid required | string | path | Stock item id (UUID) |
curl -X DELETE \ -H "Authorization: Bearer YOUR_KEY" \ https://api.shopl.io/api/v1/products/PRODUCT_ID/stock/STOCK_ID
200 OK { "success": true, "data": { "id": "9f8e7d6c-2b1a-4c3d-9e8f-7a6b5c4d3e21", "deleted": true } }
Delete stock in bulk
POST /products/:id/stock/delete
Permanently removes up to 500 unsold stock items of one product in one call.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
ids required | string[] | body | 1 to 500 stock item ids. Every one must be a UUID. A repeated id counts once |
variant_id | string | body | Limits the delete to one variant. It must belong to the product |
{
"ids": [
"9f8e7d6c-2b1a-4c3d-9e8f-7a6b5c4d3e21",
"1e2f3a4b-5c6d-4e7f-9a8b-7c6d5e4f3a2b"
],
"variant_id": "5d4c3b2a-91f0-4c6d-b7e8-2a1f0c9d8e73"
}curl -X POST \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"ids": ["9f8e7d6c-2b1a-4c3d-9e8f-7a6b5c4d3e21",
"1e2f3a4b-5c6d-4e7f-9a8b-7c6d5e4f3a2b"]}' \
https://api.shopl.io/api/v1/products/PRODUCT_ID/stock/delete200 OK { "success": true, "data": { "deleted": 1, "skipped": ["1e2f3a4b-5c6d-4e7f-9a8b-7c6d5e4f3a2b"] } }
- skipped lists the ids that were not deleted: sold, unknown, or outside the variant you named.