Products and variants API
Six endpoints, none of which deletes anything. Deleting a product also destroys its unsold stock, so that stays in the dashboard.
On this page
The product object
| Field | Type | Notes |
|---|---|---|
id | string | UUID |
shop_id | string | The shop the product belongs to |
name | string | Up to 200 characters |
description, short_desc | string | Long text and the line on the product card |
category | string | Left out when the product has none |
price | number | 0 when the product has variants |
currency | string | USD, EUR, GBP or PLN |
stock_type | string | keys, files, accounts or text |
image_url | string | Empty when no image is set |
is_active | boolean | false means hidden from the storefront |
min_quantity, max_quantity | integer | Quantity limits per checkout |
allow_balance_payment | boolean | Whether store balance may pay for it |
delivery_note | string | The message to the buyer |
sort_order | integer | Position on the storefront |
total_sold | integer | Units sold |
stock_count | integer | Unsold items available now |
has_variants | boolean | Read this before reading variants |
variants | array | Present only when the product has variants |
created_at, updated_at | string | Timestamps |
allow_preorder and preorder_deadline_days are present only when pre-orders are on for the product.
The variant object
| Field | Type | Notes |
|---|---|---|
id, product_id | string | UUIDs |
name | string | Up to 200 characters |
price | number | The price of this variant |
stock_type | string | keys, files, accounts or text |
image_url | string | Empty when none is set |
min_quantity, max_quantity | integer | 0 means the product's limit |
sort_order | integer | Position among the variants |
is_active | boolean | false means hidden |
stock_count | integer | Unsold items of this variant |
To add stock to a product or a variant, see the Stock API.
List products
GET /products
Lists every product in the shop, hidden ones included, with variants and live stock counts.
| Parameter | Type | In | Rules |
|---|---|---|---|
page | integer | query | From 1. Default 1 |
limit | integer | query | Default 20, maximum 100. A larger value is lowered to 100 |
curl -H "Authorization: Bearer YOUR_KEY" \ "https://api.shopl.io/api/v1/products?page=1&limit=20"
200 OK { "success": true, "data": { "products": [ { "id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "shop_id": "3f2a9c1b-7d44-4e0a-9a3c-1f5b8e2d6c70", "name": "Windows 11 Pro key", "price": 7.49, "currency": "USD", "stock_type": "keys", "is_active": true, "min_quantity": 1, "max_quantity": 100, "sort_order": 0, "total_sold": 318, "has_variants": false, "stock_count": 42 } ], "total": 8, "page": 1, "limit": 20 } }
- Products come back in your display order (sort_order), then newest first.
Get a product
GET /products/:id
Returns one product with its variants and live stock counts.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
curl -H "Authorization: Bearer YOUR_KEY" \ https://api.shopl.io/api/v1/products/PRODUCT_ID
200 OK { "success": true, "data": { "id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "shop_id": "3f2a9c1b-7d44-4e0a-9a3c-1f5b8e2d6c70", "name": "Streaming plan", "price": 0, "currency": "USD", "stock_type": "accounts", "is_active": true, "has_variants": true, "stock_count": 130, "variants": [ { "id": "5d4c3b2a-91f0-4c6d-b7e8-2a1f0c9d8e73", "product_id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "name": "1 month", "price": 3.49, "stock_type": "accounts", "min_quantity": 0, "max_quantity": 0, "sort_order": 0, "is_active": true, "stock_count": 130 } ] } }
- variants is present only when the product has variants. Check has_variants before reading it.
Create a product
POST /products
Creates a product, with optional inline variants. The product and its variants are written together: either all of them exist or none do.
| Parameter | Type | In | Rules |
|---|---|---|---|
name required | string | body | Up to 200 characters on one line |
price | number | body | 0 or more. Stored as 0 when the product has variants, because each variant carries its own price |
currency | string | body | USD (default), EUR, GBP or PLN. EUR, GBP and PLN prices are converted to USD when an invoice is created |
stock_type | string | body | keys (default), files, accounts or text |
description | string | body | Up to 50,000 characters. Line breaks allowed |
short_desc | string | body | Up to 500 characters |
category | string | body | Up to 48 characters on one line |
image_url | string | body | An http or https URL of up to 2,048 bytes, or an /uploads/images/ path from the dashboard uploader. The API takes no file upload |
min_quantity | integer | body | Smallest quantity per checkout. 0 or absent means 1 |
max_quantity | integer | body | Largest quantity per checkout. 0 or absent means 100 |
delivery_note | string | body | Message shown to the buyer with the delivered items. Up to 2,000 characters |
is_active | boolean | body | Default true. false creates the product hidden from the storefront |
allow_preorder | boolean | body | Default false. Lets the product be bought while it is sold out, when the shop has pre-orders on |
preorder_deadline_days | integer | body | 1 to 30. Stored only when allow_preorder is true |
variants | array | body | Up to 200 entries. Each takes name, price, stock_type, image_url, min_quantity, max_quantity and sort_order. An entry with no name is skipped |
{
"name": "Streaming plan",
"description": "Full description. Line breaks are allowed.",
"short_desc": "Shown on the product card",
"category": "Streaming",
"price": 0,
"currency": "USD",
"stock_type": "accounts",
"image_url": "https://cdn.example.com/plan.png",
"min_quantity": 1,
"max_quantity": 10,
"delivery_note": "Sign in at the provider and change the password.",
"is_active": false,
"variants": [
{ "name": "1 month", "price": 3.49 },
{ "name": "12 months", "price": 29.99 }
]
}curl -X POST \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Windows 11 Pro key","price":7.49,"currency":"USD"}' \
https://api.shopl.io/api/v1/products201 Created { "success": true, "data": { "id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "shop_id": "3f2a9c1b-7d44-4e0a-9a3c-1f5b8e2d6c70", "name": "Windows 11 Pro key", "price": 7.49, "currency": "USD", "stock_type": "keys", "is_active": true, "min_quantity": 1, "max_quantity": 100, "sort_order": 0, "has_variants": false, "stock_count": 0 } }
- Create a product hidden with "is_active": false, push its stock, then publish it with a PATCH. The storefront then never shows it empty.
- "allow_balance_payment": false is ignored on create. Send it in a PATCH afterwards.
- Creates for one shop run one at a time. Send them in sequence and the 409 does not occur.
Update a product
PATCH /products/:id
Changes the fields you send and leaves the rest as they are. The response is the product as GET returns it.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
name | string | body | Up to 200 characters on one line |
price | number | body | 0 or more. Stored as 0 when the product has variants, because each variant carries its own price |
currency | string | body | USD (default), EUR, GBP or PLN. EUR, GBP and PLN prices are converted to USD when an invoice is created |
stock_type | string | body | keys (default), files, accounts or text |
description | string | body | Up to 50,000 characters. Line breaks allowed |
short_desc | string | body | Up to 500 characters |
category | string | body | Up to 48 characters on one line |
image_url | string | body | An http or https URL of up to 2,048 bytes, or an /uploads/images/ path from the dashboard uploader. The API takes no file upload |
min_quantity | integer | body | Smallest quantity per checkout. 0 or absent means 1 |
max_quantity | integer | body | Largest quantity per checkout. 0 or absent means 100 |
delivery_note | string | body | Message shown to the buyer with the delivered items. Up to 2,000 characters |
is_active | boolean | body | Default true. false creates the product hidden from the storefront |
allow_preorder | boolean | body | Default false. Lets the product be bought while it is sold out, when the shop has pre-orders on |
preorder_deadline_days | integer | body | 1 to 30 |
sort_order | integer | body | Position on the storefront. Lower comes first |
allow_balance_payment | boolean | body | Whether customers may pay for this product with store balance |
{
"price": 9.99,
"currency": "EUR",
"is_active": false,
"category": "",
"max_quantity": 50,
"sort_order": 3,
"allow_balance_payment": false,
"allow_preorder": true,
"preorder_deadline_days": 14
}curl -X PATCH \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"price":9.99,"is_active":false}' \
https://api.shopl.io/api/v1/products/PRODUCT_ID200 OK { "success": true, "data": { "id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "name": "Windows 11 Pro key", "price": 9.99, "currency": "USD", "is_active": false, "has_variants": false, "stock_count": 42 } }
- An empty string clears category, description, short_desc, delivery_note and image_url. An empty name or stock_type answers 400, and an empty currency is read as USD.
- Changing currency changes what new checkouts charge. Existing orders keep their amounts.
- A length limit is checked only when the value you send differs from the stored one.
- There is no delete route. Deleting a product also destroys its unsold stock, so that stays in the dashboard.
Add a variant
POST /products/:id/variants
Adds one variant to a product. Its quantity limits must fit inside the product's.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
name required | string | body | Up to 200 characters on one line |
price | number | body | 0 or more |
stock_type | string | body | keys, files, accounts or text. Absent means the product's type |
image_url | string | body | Same rule as a product image |
min_quantity | integer | body | 0 means the product's minimum |
max_quantity | integer | body | 0 means the product's maximum |
sort_order | integer | body | Position among the variants. Lower comes first |
{
"name": "12 months",
"price": 29.99,
"stock_type": "accounts",
"image_url": "",
"min_quantity": 0,
"max_quantity": 0,
"sort_order": 1
}curl -X POST \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"12 months","price":29.99}' \
https://api.shopl.io/api/v1/products/PRODUCT_ID/variants201 Created { "success": true, "data": { "id": "5d4c3b2a-91f0-4c6d-b7e8-2a1f0c9d8e73", "product_id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "name": "12 months", "price": 29.99, "stock_type": "accounts", "image_url": "", "min_quantity": 0, "max_quantity": 0, "sort_order": 1, "is_active": true, "stock_count": 0 } }
- The response echoes the stored 0 for a quantity limit, not the limit checkout applies. Read the product for that.
- Adding a variant waits for stock pushes, stock edits and other variant creates on the same product. If it waits longer than five seconds it answers 409.
Update a variant
PATCH /products/:id/variants/:vid
Changes the fields you send on one variant. "is_active": false hides the variant and leaves its stock alone.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Product id (UUID) |
vid required | string | path | Variant id (UUID). It must belong to the product in the URL |
name | string | body | Up to 200 characters on one line |
price | number | body | 0 or more |
stock_type | string | body | keys, files, accounts or text |
image_url | string | body | Same rule as a product image |
min_quantity | integer | body | 0 means the product's minimum |
max_quantity | integer | body | 0 means the product's maximum |
sort_order | integer | body | Position among the variants |
is_active | boolean | body | false hides the variant from the storefront |
{
"name": "12 months",
"price": 24.99,
"sort_order": 2,
"is_active": false
}curl -X PATCH \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"price":24.99}' \
https://api.shopl.io/api/v1/products/PRODUCT_ID/variants/VARIANT_ID200 OK { "success": true, "data": { "id": "5d4c3b2a-91f0-4c6d-b7e8-2a1f0c9d8e73", "product_id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "name": "12 months", "price": 24.99, "is_active": false, "stock_count": 118 } }
- There is no delete route. Deleting a variant also removes its unsold stock, so that stays in the dashboard.