Deleting documents
Delete a document, some of its items or a single variant, and check beforehand whether the delete is allowed.
You can delete at three levels: the whole document, one or more of its items, or one variant of an item. Each DELETE has a matching check-delete endpoint that tells you in advance whether it would succeed.
| Delete | Check first |
|---|---|
DELETE …/{documentId} | GET …/{documentId}/check-delete |
DELETE …/{documentId}/items?itemIds=1&itemIds=2 | GET …/{documentId}/items/check-delete?itemIds=1&itemIds=2 |
DELETE …/{documentId}/items/{itemId}/variants/{variantId} | GET …/{documentId}/items/{itemId}/variants/{variantId}/check-delete |
The item endpoints take the ids as a repeated itemIds query parameter. Send at most 1000 ids per call; more are rejected.
A delete is permanent
Deleting a document removes it together with its items and their variants. There is no undo and no recycle bin.
Always check first
A record can only be deleted while nothing else in WinShop refers to it. Documents are often linked to each other, so this is common in practice.
Call the matching check-delete before every delete. It returns a DocumentDeleteCheckResponse:
{
"canBeDeleted": false,
"blockingReasons": ["ITEMS_BLOCKED"]
}| Field | Meaning |
|---|---|
canBeDeleted | true when nothing blocks the delete right now. |
blockingReasons | Why not. An empty array when canBeDeleted is true. |
The reasons are stable codes you can branch on:
| Reason | Meaning | What to do |
|---|---|---|
HEADER_BLOCKED | The document as a whole is still referenced by another record. | The document cannot be deleted. If the business intent is a cancellation, set a cancelled state instead, or ask a WinShop user to resolve the dependent record first. |
ITEMS_BLOCKED | At least one item is still referenced elsewhere. On the document-level check this blocks the whole document; on the items check it concerns the ids you passed. | Check the items one by one to find the blocked ones. Delete the rest if that still makes sense, or leave the document alone. |
ITEM_VARIANT_BLOCKED | The variant is still referenced elsewhere. | Leave the variant in place. |
The check is advice, not a reservation. The DELETE checks again inside its own transaction, so a delete can still fail if something changed in between. In that case it answers 400 with a message such as Document cannot be deleted. Handle that the same way as a negative check.
Example
Check, then delete an internet order:
curl https://<your-instance>/api/documents/orders/internet/8841/check-delete \
-H "Authorization: Bearer $ACCESS_TOKEN"
# only when canBeDeleted is true:
curl -X DELETE https://<your-instance>/api/documents/orders/internet/8841 \
-H "Authorization: Bearer $ACCESS_TOKEN"Deleting two items of the same order works the same way, with the ids in the query string:
curl "https://<your-instance>/api/documents/orders/internet/8841/items/check-delete?itemIds=301554&itemIds=301555" \
-H "Authorization: Bearer $ACCESS_TOKEN"
curl -X DELETE "https://<your-instance>/api/documents/orders/internet/8841/items?itemIds=301554&itemIds=301555" \
-H "Authorization: Bearer $ACCESS_TOKEN"Other things to know
- A processed document is closed for changes. See Lifecycle.
- After items or variants are deleted, the totals of the document are recalculated.
- Not every document family can be deleted through the API. Invoices and POS receipts are read-only.
Reference for the example: Check delete, Delete, Check delete items, Delete items, Check delete item variant, Delete item variant.