Catalog

The catalog is everything that describes what the company sells: products, their prices, how much of each is in stock, and the promotions that change a price. This page explains how those pieces relate and where to find them.

ProductsCopy Anchor Link

A product is one line of the assortment: a name, a code, a unit, a VAT rate and a long list of attributes. Products live under /api/products.

A product's detail is large. Its sub-collections are loaded only when you ask for them with the details query parameter, for example Barcodes, Units, Prices, Photos or ColorSizeVariants. Without details you get the header only, which is much cheaper.

curl "https://<your-instance>/api/products/5120?details=Barcodes&details=ColorSizeVariants" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "productId": 5120,
  "productCode": "TS-BASIC",
  "productName": "T-shirt Basic",
  "unitId": 1,
  "isColorAndSize": true,
  "isInactive": false,
  "lastModify": "2026-10-09T08:12:44",
  "barcodes": [{ "id": 9001, "barcode": "8590000051201", "colorId": 4, "sizeId": 12, "isMain": true }],
  "colorSizeVariants": [
    { "id": 70011, "productId": 5120, "colorId": 4, "sizeId": 12 },
    { "id": 70012, "productId": 5120, "colorId": 4, "sizeId": 13 }
  ]
}

(Shortened.)

Two things to know:

• The id of a product is called productId, not id.
• A product with isColorAndSize: true is sold in variants: combinations of colour, size, length and dimension. colorSizeVariants lists the combinations that exist. The names behind the ids come from the item lists.

Reference: Product.

Price list and price levelsCopy Anchor Link

WinShop keeps up to 15 selling prices for every product. They are called price levels. A customer is assigned one level, so a wholesale partner can buy at level 3 while the e-shop sells at level 1.

What each level means is decided by the customer and differs between instances. There is no fixed "retail" or "wholesale" level. Ask the customer which level your integration should use and keep the number in your configuration.

The product search returns all levels on every row, each in two fields:

That list is the price list: the catalog view of products with their selling prices. In the reference it has its own section, Price list, although its route is POST /api/products/filter-paginated.

A level price is a list price. The price a specific customer actually pays can also depend on discounts and promotions. GET /api/products/{productId}/price resolves that final price for a warehouse and, optionally, a customer. See Get product price.

Repricing records have their own section in the reference: Product repricing.

Stock itemsCopy Anchor Link

A stock item is the holding of one product, or one variant of a product, in one warehouse. If a T-shirt comes in six variants and is stocked in two warehouses, it has up to twelve stock items.

Stock items live under /api/stock-items. Search them with POST /api/stock-items/filter-paginated, usually filtered by warehouseId. Each row carries the quantities for that product, variant and warehouse, such as quantityInStock and quantityAvailable.

Stock normally moves when a document is processed: an intake adds goods, a delivery note removes them.

The Stock levels sync guide explains the quantity fields. Reference: Stock items.

PromotionsCopy Anchor Link

Promotions are price rules that the customer configures in WinShop. They are applied automatically whenever a price is resolved, for example at the cash register or by the price endpoint above. The promotion endpoints let you read that configuration, so that an e-shop can show the same offers.

WinShop has several families of promotions, each with its own route under /api/promotions/:

Every family has a GET for the whole list and a GET …/{id} for one promotion. They are read-only, with one exception: one-time barcode discounts can also be created and updated through the API.

Each family has its own model, so read the schema of the one you need in the reference. The promotion sections sit under Promotions in the reference sidebar; start with Item promotions.