Anatomy of a document
What a WinShop document is - header, items and variants - and which document families the API exposes.
In WinShop, a document is a business record that moves goods or money: an order, a delivery note, a goods intake, an invoice, a claim. Most of what an integration writes to WinShop is a document.
Every document type has its own endpoints, but they all have the same structure and nearly the same set of operations. Learn one and you know them all.
Header, items, variants
A document has three levels:
- The header: who, where and when. The customer or supplier, the warehouse, dates, totals, the state.
items[]: one entry per product on the document, with quantity, unit, price and VAT rate.variants[]inside an item: if the product is sold in variants, the quantity split by colour, size, length and dimension.
A variant is one combination of colour, size, length and dimension of a product, such as "red, size M". The ids come from the item lists of the same names.
curl https://<your-instance>/api/documents/expedition/delivery-notes/77120 \
-H "Authorization: Bearer $ACCESS_TOKEN"{
"id": 77120,
"internalNumber": 2600418,
"formNumber": "DN-2026-0418",
"customerId": 1042,
"warehouseId": 1,
"dateOfOrder": "2026-10-09T00:00:00",
"documentStateId": 2,
"isProcessed": false,
"isLocked": false,
"totalPriceWoVat": 700,
"totalPrice": 847,
"items": [
{
"id": 301554,
"productId": 5120,
"unitIdIssued": 1,
"quantityIssued": 3,
"priceWoVat": 100,
"price": 121,
"vatRate": 21,
"variants": [
{ "id": 880121, "itemId": 301554, "colorId": 4, "sizeId": 12, "quantity": 2 },
{ "id": 880122, "itemId": 301554, "colorId": 4, "sizeId": 13, "quantity": 1 }
]
},
{
"id": 301555,
"productId": 733,
"unitIdIssued": 1,
"quantityIssued": 4,
"priceWoVat": 100,
"price": 121,
"vatRate": 21
}
]
}(Shortened. The real response has many more fields; see Get a delivery note.)
The first item is a product with variants: three pieces, two in one size and one in another. The second is a plain product without variants.
Three numbers identify a document
| Field | What it is |
|---|---|
id | The database id. This is the {documentId} in every URL. |
internalNumber | The document number WinShop assigns when the document is created. |
formNumber | A free-text number. By WinShop convention it holds the number of the document in the outside world: a supplier's invoice number, an e-shop order number. Use it for your own reference. |
Rules for items and variants
- A new item needs a
productId. On an existing item the product cannot be changed. - For a product with variants, give the quantities in
variants[]. If you also send a quantity on the item, it must equal the sum of the variant quantities. - A variant is identified by its combination of
colorId,sizeId,lengthIdanddimensionId. The combination must exist for the product and may appear only once per item.
Document families
All document routes start with /api/documents/.
| Family | Route | What it is |
|---|---|---|
| Intakes | intakes | Goods received into a warehouse. |
| Delivery notes | expedition/delivery-notes | Goods issued from a warehouse to a customer. |
| Write-offs | expedition/write-offs | Goods removed from stock without a sale. |
| Internal transfers | internal-transfers | Goods moved between two warehouses. |
| Invoices | invoices | Invoices. Read-only: search, detail and PDF. They are created from delivery notes. |
| Customer orders | orders/customer | Orders from customers. |
| Internet orders | orders/internet | Orders that come from an e-shop. See the E-shop orders guide. |
| Internal orders | orders/internal | Orders raised inside the company. |
| Supplier orders | orders/supplier | Purchase orders sent to suppliers. |
| Order delivery addresses | orders/delivery-address | Not a document itself: an address record that orders point to with deliveryAddressId. |
| Claims | claims/customer, claims/internal, claims/supplier | Complaints and returns. |
| Stock taking | stock-taking/stock-takings, stock-taking/inventory-backups | Inventory counts and their snapshots. |
| Point of sale | pos/receipts, pos/shopping-session | Receipts and open baskets of the cash registers. |
Not every family has every operation. Invoices and POS receipts can only be read, and only the documents that move stock can be processed. The reference shows what each one offers.
Document state is data, not a state machine
WinShop does not have one fixed workflow such as "new, confirmed, shipped". Each customer defines their own list of states and what they mean, and the list is different on every instance.
-
The state is an id that points to an item list. The field is
documentStateIdon intakes, delivery notes, internal transfers and claims, andcustomDocumentStateIdon orders. -
Each document type reads its states from its own item list. Do not reuse an id from one list on another document type. The one exception is delivery notes and internal transfers, which share the same states.
Documents States item list Orders /api/item-lists/documents/orders/statesIntakes /api/item-lists/documents/intakes/statesDelivery notes /api/item-lists/documents/delivery-notes/statesInternal transfers /api/item-lists/documents/internal-transfers/statesClaims /api/item-lists/documents/claims/states -
Ask the customer which states your integration should set and which it should react to. Keep that mapping in your configuration.
Apart from the customer-defined state, a document has a few built-in flags that do have fixed meaning. The most important are isProcessed (the document has been posted and can no longer be changed) and isLocked (someone has it open for editing). Both are explained in Lifecycle.