API · ProductsDocs navigation

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

FieldTypeNotes
idstringUUID
shop_idstringThe shop the product belongs to
namestringUp to 200 characters
description, short_descstringLong text and the line on the product card
categorystringLeft out when the product has none
pricenumber0 when the product has variants
currencystringUSD, EUR, GBP or PLN
stock_typestringkeys, files, accounts or text
image_urlstringEmpty when no image is set
is_activebooleanfalse means hidden from the storefront
min_quantity, max_quantityintegerQuantity limits per checkout
allow_balance_paymentbooleanWhether store balance may pay for it
delivery_notestringThe message to the buyer
sort_orderintegerPosition on the storefront
total_soldintegerUnits sold
stock_countintegerUnsold items available now
has_variantsbooleanRead this before reading variants
variantsarrayPresent only when the product has variants
created_at, updated_atstringTimestamps

allow_preorder and preorder_deadline_days are present only when pre-orders are on for the product.

The variant object

FieldTypeNotes
id, product_idstringUUIDs
namestringUp to 200 characters
pricenumberThe price of this variant
stock_typestringkeys, files, accounts or text
image_urlstringEmpty when none is set
min_quantity, max_quantityinteger0 means the product's limit
sort_orderintegerPosition among the variants
is_activebooleanfalse means hidden
stock_countintegerUnsold items of this variant

To add stock to a product or a variant, see the Stock API.

List products

GET /products

Scope read_products

Lists every product in the shop, hidden ones included, with variants and live stock counts.

ParameterTypeInRules
pageintegerqueryFrom 1. Default 1
limitintegerqueryDefault 20, maximum 100. A larger value is lowered to 100
Request
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

Scope read_products

Returns one product with its variants and live stock counts.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
Request
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.
ErrorStatusWhen
Product not found404No product with that id in this shop.

Create a product

POST /products

Scope write_products

Creates a product, with optional inline variants. The product and its variants are written together: either all of them exist or none do.

ParameterTypeInRules
name requiredstringbodyUp to 200 characters on one line
pricenumberbody0 or more. Stored as 0 when the product has variants, because each variant carries its own price
currencystringbodyUSD (default), EUR, GBP or PLN. EUR, GBP and PLN prices are converted to USD when an invoice is created
stock_typestringbodykeys (default), files, accounts or text
descriptionstringbodyUp to 50,000 characters. Line breaks allowed
short_descstringbodyUp to 500 characters
categorystringbodyUp to 48 characters on one line
image_urlstringbodyAn 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_quantityintegerbodySmallest quantity per checkout. 0 or absent means 1
max_quantityintegerbodyLargest quantity per checkout. 0 or absent means 100
delivery_notestringbodyMessage shown to the buyer with the delivered items. Up to 2,000 characters
is_activebooleanbodyDefault true. false creates the product hidden from the storefront
allow_preorderbooleanbodyDefault false. Lets the product be bought while it is sold out, when the shop has pre-orders on
preorder_deadline_daysintegerbody1 to 30. Stored only when allow_preorder is true
variantsarraybodyUp 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
Request body
{
  "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 }
  ]
}
Request
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/products
201 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.
ErrorStatusWhen
Product name is required400name is missing or empty.
Price cannot be negative400price is below 0 or not a number.
Currency must be USD, EUR, GBP, PLN, or a supported legacy option400currency is not on the list.
stock_type must be keys, files, accounts or text400stock_type is anything else.
variants must contain at least one named variant400variants was sent and no entry has a name.
Pre-order deadline must be between 1 and 30 days400preorder_deadline_days is outside 1 to 30.
Product limit reached. Upgrade to add more products.403The shop is at its plan's product limit.
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.

Update a product

PATCH /products/:id

Scope write_products

Changes the fields you send and leaves the rest as they are. The response is the product as GET returns it.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
namestringbodyUp to 200 characters on one line
pricenumberbody0 or more. Stored as 0 when the product has variants, because each variant carries its own price
currencystringbodyUSD (default), EUR, GBP or PLN. EUR, GBP and PLN prices are converted to USD when an invoice is created
stock_typestringbodykeys (default), files, accounts or text
descriptionstringbodyUp to 50,000 characters. Line breaks allowed
short_descstringbodyUp to 500 characters
categorystringbodyUp to 48 characters on one line
image_urlstringbodyAn 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_quantityintegerbodySmallest quantity per checkout. 0 or absent means 1
max_quantityintegerbodyLargest quantity per checkout. 0 or absent means 100
delivery_notestringbodyMessage shown to the buyer with the delivered items. Up to 2,000 characters
is_activebooleanbodyDefault true. false creates the product hidden from the storefront
allow_preorderbooleanbodyDefault false. Lets the product be bought while it is sold out, when the shop has pre-orders on
preorder_deadline_daysintegerbody1 to 30
sort_orderintegerbodyPosition on the storefront. Lower comes first
allow_balance_paymentbooleanbodyWhether customers may pay for this product with store balance
Request body
{
  "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
}
Request
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_ID
200 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.
ErrorStatusWhen
Product not found404No product with that id in this shop.
Product limits conflict with variant "12 months"400The new quantity limits do not fit a variant the product already has.
Product name is required400name was sent empty.
Price cannot be negative400price is below 0 or not a number.
stock_type must be keys, files, accounts or text400stock_type was sent empty or is anything else.
Pre-order deadline must be between 1 and 30 days400preorder_deadline_days is outside 1 to 30.

Add a variant

POST /products/:id/variants

Scope write_products

Adds one variant to a product. Its quantity limits must fit inside the product's.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
name requiredstringbodyUp to 200 characters on one line
pricenumberbody0 or more
stock_typestringbodykeys, files, accounts or text. Absent means the product's type
image_urlstringbodySame rule as a product image
min_quantityintegerbody0 means the product's minimum
max_quantityintegerbody0 means the product's maximum
sort_orderintegerbodyPosition among the variants. Lower comes first
Request body
{
  "name": "12 months",
  "price": 29.99,
  "stock_type": "accounts",
  "image_url": "",
  "min_quantity": 0,
  "max_quantity": 0,
  "sort_order": 1
}
Request
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/variants
201 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.
ErrorStatusWhen
Product not found404No product with that id in this shop.
Variant name is required400name is missing or empty.
Clear existing stock before adding variants400The product has no variants yet and still holds unsold stock added without one.
They can only be delivered from variantless stock400The product has no variants yet and orders on it still wait for delivery. The message gives the counts.
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.

Update a variant

PATCH /products/:id/variants/:vid

Scope write_products

Changes the fields you send on one variant. "is_active": false hides the variant and leaves its stock alone.

ParameterTypeInRules
id requiredstringpathProduct id (UUID)
vid requiredstringpathVariant id (UUID). It must belong to the product in the URL
namestringbodyUp to 200 characters on one line
pricenumberbody0 or more
stock_typestringbodykeys, files, accounts or text
image_urlstringbodySame rule as a product image
min_quantityintegerbody0 means the product's minimum
max_quantityintegerbody0 means the product's maximum
sort_orderintegerbodyPosition among the variants
is_activebooleanbodyfalse hides the variant from the storefront
Request body
{
  "name": "12 months",
  "price": 24.99,
  "sort_order": 2,
  "is_active": false
}
Request
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_ID
200 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.
ErrorStatusWhen
Product not found404No product with that id in this shop.
Variant not found404No such variant on that product, or the id is not a UUID.
Variant name is required400name was sent empty.

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