Item lists
The reference tables of WinShop - warehouses, units, VAT rates, colours, sizes and many more - and how to read them.
An item list is a reference table: a short list of named values that other records point to by id. Warehouses, units of measure, VAT rates, currencies, colours, sizes, payment types and document states are all item lists. WinShop has well over a hundred of them.
You meet item lists constantly, because the rest of the API stores only their ids. A product has a unitId, an order has a paymentTypeId and a warehouseId, an order item variant has a colorId and a sizeId. To show a name, or to pick the right id when you write data, you read the item list.
All item lists live under /api/item-lists/. The values are data of the instance: every customer has their own warehouses, their own colours and their own ids. Never hard-code an id from one instance into an integration that runs against another.
Simple lists
Most item lists hold nothing but an id and a name. They share one row shape, called ILItem in the reference:
{ "id": 1, "name": "E-shop CZ" }and one set of endpoints:
| Request | Result |
|---|---|
GET /api/item-lists/{list} | All rows. Item lists are small, so there is no paging. |
GET /api/item-lists/{list}/{id} | One row. |
POST /api/item-lists/{list} | Create a row. The body is IlItemCreateRequest, which is just { "name": "…" }; the server assigns the id. |
PUT /api/item-lists/{list}/{id} | Rename a row. The body is the full ILItem. |
Simple lists generally have no DELETE. Rows are referenced from all over the database, so they are meant to stay.
curl https://<your-instance>/api/item-lists/orders/eshop-sources \
-H "Authorization: Bearer $ACCESS_TOKEN"[
{ "id": 1, "name": "E-shop CZ" },
{ "id": 2, "name": "E-shop SK" }
]Complex lists
Some item lists carry more than a name. A warehouse has a number, an address and flags; a VAT rate has a percentage and a validity period; a currency has exchange rates. These "complex" lists have their own row model, documented on their reference page.
They differ from simple lists in a few ways:
- The row has more fields, and the name field is not always called
name. - Not every complex list can be written. Some are read-only and offer only the two
GETendpoints. - Where writing is allowed, the endpoints can differ from the simple lists, and some complex lists can also delete rows.
Do not assume. The reference page of each list shows exactly which methods it has.
curl https://<your-instance>/api/item-lists/vat-rates \
-H "Authorization: Bearer $ACCESS_TOKEN"[
{
"id": 1,
"name": "Basic",
"vatRate": 21,
"validFrom": "2013-01-01T00:00:00"
}
]The lists most integrations need
| List | Path | You need it for |
|---|---|---|
| Warehouses | /api/item-lists/warehouses | Stock is kept per warehouse and every document belongs to one. |
| Units | /api/item-lists/units | Units of measure of products and document items (unitId). |
| VAT rates | /api/item-lists/vat-rates | The VAT percentage behind a product's VAT rate id. |
| Currencies | /api/item-lists/currencies | Currency codes and exchange rates (currencyId). |
| Colors, Sizes, Lengths, Dimensions | /api/item-lists/colors, /sizes, /lengths, /dimensions | The four axes of a product variant. See below. |
| Variants | /api/item-lists/variants | Names behind the variantId field of document items. This is a separate simple list, not the colour and size combinations described below. |
| Payment types | /api/item-lists/payment-types | paymentTypeId on orders and delivery notes. |
| Transport types | /api/item-lists/transport-types | transportTypeId on orders and delivery notes. |
| E-shop sources | /api/item-lists/orders/eshop-sources | eshopSourceId, which says which e-shop an order came from. |
| Order states | /api/item-lists/documents/orders/states | The customer-defined states of orders. |
| Intake states | /api/item-lists/documents/intakes/states | The customer-defined states of intakes. |
| Delivery note states | /api/item-lists/documents/delivery-notes/states | The customer-defined states of delivery notes. |
| Internal transfer states | /api/item-lists/documents/internal-transfers/states | The customer-defined states of internal transfers. |
| Claim states | /api/item-lists/documents/claims/states | The customer-defined states of claims. |
Colours, sizes and variants
In WinShop a product can be sold in several variants. A variant is one combination of colour, size, length and dimension: a T-shirt in red, size M, for example. Each axis is an item list, and a variant row refers to them by colorId, sizeId, lengthId and dimensionId. A product that uses only colour and size leaves the other two out.
Read these lists once, cache them, and use them to translate ids to names in your own system. Refresh the cache when you meet an id you do not know.
Browse all lists
The reference has one page per item list: Item lists reference.