API · StockDocs navigation

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

Scope read_stock

Returns every unsold stock item of a product, oldest first, with its content decrypted.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
variant_idstringqueryLimits the list to one variant. A value that is not a UUID is ignored
Request
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.
ErrorStatusWhen
Product not found404No product with that id in this shop.

Add stock

POST /products/:id/stock

Scope write_stock

Adds stock items to a product. Each string in items becomes one unit a buyer can receive.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
items requiredstring[]bodyAt least one entry. Each entry is stored exactly as sent: not trimmed, not split and not de-duplicated
variant_idstringbodyRequired when the product has variants. Refused when it has none
notifybooleanbodyDefault false. true also refreshes the storefront cache and sends your restock alerts
Request body
{
  "items": ["AAAAA-BBBBB-CCCCC", "DDDDD-EEEEE-FFFFF"],
  "variant_id": "5d4c3b2a-91f0-4c6d-b7e8-2a1f0c9d8e73",
  "notify": true
}
Request
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/stock
201 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.
ErrorStatusWhen
Product not found404No product with that id in this shop.
items must contain at least one entry400items is missing or empty.
variant_id is required for products with variants400The product has variants and none was named.
This product has no variants400variant_id was sent for a product without variants.
Invalid variant_id400variant_id is not a UUID.
Variant not found404variant_id is not a variant of this product.
Your plan supports up to 2000 available stock items per product. This request would use 2140.403On Free, the push would take the product above 2,000 available items.
Another change to this shop's products is running right now409The write could not take its turn. Nothing was written. The response carries Retry-After: 5.

Edit a stock item

PATCH /products/:id/stock/:sid

Scope edit_stock · Also limited to 20 requests a minute, shared by the three stock edit and delete routes

Replaces the content of one unsold stock item. The response never repeats the content.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
sid requiredstringpathStock item id (UUID)
content requiredstringbodyNot empty. At most 65,536 bytes
Request body
{ "content": "NEW-CONTENT" }
Request
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_ID
200 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.
ErrorStatusWhen
Product not found404No product with that id in this shop.
content must not be empty400content is missing or empty.
content exceeds the maximum length400content is longer than 65,536 bytes.
Stock item not found or already sold404No unsold item with that id on that product. A sold item is never editable. An sid that is not a UUID answers "Stock item not found".
content matches an item this product has already sold409The shop has duplicate stock detection on and the new content was already delivered to a buyer.
Another change to this shop's products is running right now409The write could not take its turn. Nothing was written. The response carries Retry-After: 5.

Delete a stock item

DELETE /products/:id/stock/:sid

Scope delete_stock · Also limited to 20 requests a minute, shared by the three stock edit and delete routes

Permanently removes one unsold stock item. A delete cannot be undone.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
sid requiredstringpathStock item id (UUID)
Request
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
  }
}
ErrorStatusWhen
Product not found404No product with that id in this shop.
Stock item not found or already sold404No unsold item with that id. An item that sells while the request is in flight is left intact. An sid that is not a UUID answers "Stock item not found".

Delete stock in bulk

POST /products/:id/stock/delete

Scope delete_stock · Also limited to 20 requests a minute, shared by the three stock edit and delete routes

Permanently removes up to 500 unsold stock items of one product in one call.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
ids requiredstring[]body1 to 500 stock item ids. Every one must be a UUID. A repeated id counts once
variant_idstringbodyLimits the delete to one variant. It must belong to the product
Request body
{
  "ids": [
    "9f8e7d6c-2b1a-4c3d-9e8f-7a6b5c4d3e21",
    "1e2f3a4b-5c6d-4e7f-9a8b-7c6d5e4f3a2b"
  ],
  "variant_id": "5d4c3b2a-91f0-4c6d-b7e8-2a1f0c9d8e73"
}
Request
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/delete
200 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.
ErrorStatusWhen
Product not found404No product with that id in this shop.
ids must contain at least one entry400ids is missing or empty.
ids must contain at most 500 entries400More than 500 ids were sent.
ids must all be valid UUIDs400One id is malformed. Nothing is deleted.
Invalid variant_id400variant_id is not a UUID.
variant_id does not belong to this product400variant_id names a variant of another product.

If the docs do not cover it, ask on Telegram or use the contact form.