> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# API reference orders
> Manage shop orders via the Admin Interface API: retrieve order data, update delivery and payment status, and delete records using the orders endpoint.
The `orders/` endpoint provides you with an interface for managing order data in our shop system. With this interface, you can retrieve order data, delete it, and update its status.
***
## Supported methods
List of all supported methods.
| **Command/info** | **Endpoints** | **GET** | **PUT** | **POST** | **DELETE** |
| ---------------- | ------------- | --------------------- | --------------------- | ------------------- | --------------------- |
| **Orders** | orders/ | | | | |
## Data fields of an order
| **Name** | **Type** | **Meaning** |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **createdAt** | String | Time the order was placed (ISO 8601 format, UTC). |
| **updatedAt** | String | Time of the last modification (ISO 8601 format, UTC).
Only included in the list view. |
| **payedAt** | String | Time of payment (ISO 8601 format, UTC).
Only included in the list view. |
| **isImported** | Boolean | Indicates whether the order was imported.
Only included in the list view. |
| **deleted** | Boolean | Indicates whether the order has been deleted. |
| **deliveryStatus** | Object | Information about shipment |
| **id** | String | Unique ID of the order. |
| **paymentStatus** | Integer | Payment status (e.g. open, paid, failed)
Possible values:
0 = `Pending`
1 = `Finished`
2 = `Error`
3 = `Redirected`
4 = `CanceledByUser`
5 = `Rejected`
6 = `CanceledByAdmin`
7 = `Refunded`
8 = `RefundedPartially`
|
| **processingStatus** | Integer | Order processing status
Possible values:
0 = `New`
1 = `Finished`
2 = `Deleted`
3 = `Canceled` |
| **verificationStatus** | Integer | Status of order authenticity (e.g. genuine, test order)
Possible values:
0 = `Default`
1 = `Test`
2 = `Fake` |
| **verificationComment** | Object | Comment about the order verification. Optionally contains the fields `title` (String) and `comment` (String). |
| **subshopId** | String | ID of the subshop through which the order was completed. |
| **data.general.dateTime** | String | Order time according to metadata (ISO 8601 format, UTC). |
| **data.general.orderId** | String | Unique ID of the order. |
| **data.general.sessionId** | String | ID of the session in which the order was completed. |
| **data.general.shopId** | String | Technical name of the shop. |
| **data.general.shopLanguage** | String | Language of the shop during the order. |
| **data.general.subshopId** | String | Subshop ID from metadata (redundant with the field above). |
| **data.general.testMode** | Boolean | Indicates whether the order was created in test mode. |
| **data.customer.accountId** | Integer | ID of the customer account that placed the order. |
| **data.customer.accountType** | String | Type of the customer account.
Possible values:
`"new"`
`"registered"`
`"guest"` |
| **data.customer.customerNumber** | String | Customer number (if assigned). |
| **data.customer.deviceType** | Integer | Device type of the customer at checkout. `1` – Desktop, `2` – Mobile, `3` – Tablet. |
| **data.customer.email** | String | Email address of the customer. |
| **data.customer.ipAddress** | String | IP address of the customer at the time of the order. |
| **data.customer.platformType** | Integer | Platform type of the customer. `1` – Web, `2` – App. |
| **data.shippingAddress** | Object ([**Address**](/en/schnittstellen/admin-interface-api/api-referenz-kundendaten#4-methoden-für-adressen-und-bankdaten)) | Shipping address |
| **data.billAddress** | Object ([**Address**](/en/schnittstellen/admin-interface-api/api-referenz-kundendaten#4-methoden-für-adressen-und-bankdaten)) | Billing address |
| **data.order.currencyIso** | String | ISO code of the currency (e.g. EUR). |
| **data.order.currencySymbol** | String | Currency symbol (e.g. €). |
| **data.order.defaultTaxRate** | String | Default VAT rate. |
| **data.order.delivererId** | String | ID of the shipping service provider. |
| **data.order.delivererOrderText** | String | Display name of the shipping service provider. |
| **data.order.deliveryCost** | String | Shipping cost (gross). |
| **data.order.deliveryTaxRate** | String | VAT rate on shipping. |
| **data.order.paymentId** | String | ID of the chosen payment method. |
| **data.order.paymentOrderText** | String | Display name of the payment method. |
| **data.order.priceType** | String | Price specification: "gross" or "net". |
| **data.order.referer** | String | Origin URL of the order. |
| **data.order.subreferer** | String | Additional origin information. |
| **data.order.subtotal** | String | Subtotal of the products. |
| **data.order.tax** | String | Total amount of taxes. |
| **data.order.total** | String | Total amount of the order (incl. shipping and discounts). |
| **data.order.totalCommission** | String | Total commission. |
| **data.order.totalDiscount** | String | Total discount amount. |
| **data.order.totalVoucher** | String | Total redeemed voucher value. |
| **data.order.totalWeight** | number | Total weight of the order. |
| **data.orderList.item\[].basketId** | String | ID of the basket entry. |
| **data.orderList.item\[].discount** | String | Discount on this item. |
| **data.orderList.item\[].extraFields** | Object | User-defined fields of the basket item. |
| **data.orderList.item\[].isAutoBasket** | Boolean | Item automatically placed in the basket. |
| **data.orderList.item\[].isChangeable** | Boolean | Basket item can be changed. |
| **data.orderList.item\[].isRemovable** | Boolean | Basket item can be removed. |
| **data.orderList.item\[].isVisible** | Boolean | Indicates whether the automatically added item is visible in the basket. |
| **data.orderList.item\[].itemNumber** | String | Item number. |
| **data.orderList.item\[].name** | String | Item name. |
| **data.orderList.item\[].orgPrice** | String | Original price (before discount). |
| **data.orderList.item\[].price** | String | Price per unit. |
| **data.orderList.item\[].productId** | String | Product ID. |
| **data.orderList.item\[].quantity** | String | Ordered quantity. |
| **data.orderList.item\[].singleTotal** | String | Total price of this item (quantity × price). |
| **data.orderList.item\[].taxId** | String | Tax ID. |
| **data.orderList.item\[].taxRate** | String | VAT rate. |
| **data.orderList.item\[].total** | String | Final price of this item (incl. discount, etc.). |
| **data.orderList.item\[].variantId** | String | Variant ID. |
| **data.orderList.item\[].variantSelection\[]** | Object\[] | Variant selection of the item. |
| **data.orderList.item\[].variantSelection\[].attributeId** | String | Name of the variant attribute (e.g. "Size"). |
| **data.orderList.item\[].variantSelection\[].optionId** | String | Selected option (e.g. "M"). |
| **data.orderList.item\[].weight** | Float | Weight of the item. |
| **data.freeFields** | Object | User-defined fields of the order |
| **data.vouchers\[].id** | String | Voucher code. |
| **data.vouchers\[].name** | String | Name of the voucher. |
| **data.vouchers\[].charge** | String | ID of the voucher charge. |
| **data.vouchers\[].value** | String | Original voucher value. |
| **data.vouchers\[].rest** | String | Remaining value of the voucher after redemption. |
| **data.vouchers\[].taxId** | String | Tax ID for voucher. |
| **data.vouchers\[].taxRate** | Float | Tax rate for voucher. |
### Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"createdAt": "2025-04-16T13:02:43Z",
"data": {
"billAddress": {
"additionalInfo": "",
"addressType": "1",
"businessFax": "",
"businessPhone": "",
"city": "asdf",
"company": "WEBSALE AG",
"country": "DE",
"countryName": "Deutschland",
"custom": null,
"dateOfBirth": "",
"department": "",
"fax": "",
"firstName": "asdff",
"lastName": "asdf",
"mobilePhone": "",
"phone": "987",
"salutationCode": "1",
"salutationText": "Herr",
"state": "",
"street": "asdf",
"streetNumber": "9",
"taxId": "",
"titleCode": "2",
"titleText": "Dr.",
"zip": "99999"
},
"computop-hosted": {},
"customer": {
"accountId": 1,
"accountType": "registered",
"customerNumber": "",
"deviceType": 1,
"email": "root@root.root",
"ipAddress": "172.18.0.1",
"platformType": 1
},
"dummy": {},
"freeFields": {
"agb.checked": "true",
"agb.merchantText": "agb text here",
"comment.text": ""
},
"general": {
"dateTime": "2025-04-16T13:02:43Z",
"orderId": "1300",
"sessionId": "d25e2c0b739aacdf4d3e55727ea6ffae943ebf15021ac1d6b60ba5f5c5d04582",
"shopId": "",
"shopLanguage": "Deutsch",
"subshopId": "deutsch",
"testMode": false
},
"order": {
"currencyIso": "EUR",
"currencySymbol": "€",
"defaultTaxRate": "0.1900000",
"delivererId": "hermes",
"delivererOrderText": "Hermes",
"deliveryCost": "3.95",
"deliveryTaxRate": "0.1900000",
"paymentId": "safepayment",
"paymentOrderText": "Sichere Zahlungsart",
"priceType": "gross",
"referer": "https://myshop.localhost/?wsvc=View&view=confirm.htm",
"subreferer": "",
"subtotal": "10.00",
"tax": "0.63",
"total": "3.95",
"totalCommission": "0.00",
"totalDiscount": "0.00",
"totalVoucher": "10.00",
"totalWeight": 0
},
"orderList": {
"item": [
{
"basketId": "9680cda2830c10b063ca",
"discount": "0.00",
"extraFields": {},
"isAutoBasket": false,
"isChangeable": true,
"isRemovable": true,
"isVisible": true,
"itemNumber": "8765",
"name": "Something2",
"orgPrice": "0.00",
"price": "5.00",
"productId": "143-68071",
"quantity": "1.00",
"singleTotal": "5.00",
"taxId": "19",
"taxRate": "0.1900000",
"total": "5.00",
"variantId": "",
"variantSelection": null,
"weight": 0
},
{
"basketId": "0d191c832e46f326fc420dc59aa9facfc69f2fda5a5cad2e26d...",
"discount": "0.00",
"extraFields": {},
"isAutoBasket": true,
"isChangeable": false,
"isRemovable": false,
"isVisible": true,
"itemNumber": "12341234",
"name": "myProduct",
"orgPrice": "0.00",
"price": "5.00",
"productId": "105-59442",
"quantity": "1.00",
"singleTotal": "5.00",
"taxId": "19",
"taxRate": "0.1900000",
"total": "5.00",
"variantId": "1",
"variantSelection": [
{
"attributeId": "Color",
"optionId": "red"
},
{
"attributeId": "Size",
"optionId": "M"
}
],
"weight": 0
}
]
},
"paypal-checkout": {
"executePayPalResponse": "",
"expressCheckout": "false",
"orderID": "",
"paymentAction": "CAPTURE",
"paymentID": "",
"paymentMode": "PayPal",
"paypalStatus": ""
},
"shippingAddress": null,
"vouchers": [
{
"charge": "121",
"id": "93JC-TGGL-KA3M-MRA7",
"name": "myVoucher",
"rest": "0.00",
"taxId": "19",
"taxRate": 0.19,
"value": "55.00"
}
]
},
"deleted": false,
"deliveryStatus": {},
"id": "1300",
"paymentStatus": 1,
"processingStatus": 0,
"subshopId": "deutsch",
"verificationComment": {},
"verificationStatus": 0
}
```
## Using the methods
### GET orders
This method returns a list of all orders from the admin interface of the shop.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/orders
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"accountId": 1,
"createdAt": "2024-11-07T17:38:32Z",
"data": {
"billAddress": {
"country": "DE",
"countryName": "Deutschland",
"firstName": "asdf",
...
},
"computop-hosted": {},
"customer": {
"accountId": 1,
"accountType": "registered",
"email": "root@root.root",
"ipAddress": "172.18.0.1"
},
"dummy": {},
"freeFields": {
"agb.checked": "true",
"agb.merchantText": "agb text here",
"comment.text": ""
},
"general": {
"dateTime": "2024-11-07T17:38:32Z",
"orderId": "820",
"sessionId": "79d803076669c8a41874d9d2cd8451f...",
"shopId": "myshop",
"shopLanguage": "",
"subshopId": "deutsch",
"testMode": false
},
"order": {
"currencyIso": "EUR",
"currencySymbol": "€",
"defaultTaxRate": "0.1900000",
"delivererId": "dhl",
"delivererOrderText": "DHL",
"deliveryCost": "11.00",
"deliveryTaxRate": "0.1900000",
"paymentId": "bill",
"paymentOrderText": "Rechnung",
"priceType": "gross",
"subtotal": "5.00",
"tax": "2.55",
"total": "16.00",
"totalCommission": "0.00",
"totalDiscount": "0.00",
"totalVoucher": "0.00"
},
"orderList": {
"item": [
{
"basketId": "d0c04a4cb60f708288a2",
"freeFields": {
"gravur1": "",
"gravur2": "",
"gravur3": ""
},
"isAutoBasket": false,
"isChangeable": true,
"isRemovable": true,
"isVisible": true,
"itemNumber": "8",
"name": "T-Shirt 'Land Rover' in Hellgrau",
"price": "5.00",
"productId": "105-59442",
"quantity": "1.00",
"singleTotal": "5.00",
"taxId": "19",
"taxRate": "0.1900000",
"total": "5.00",
"variantId": "1",
"variantSelection": [
{
"attributeId": "555",
"optionId": "foo"
},
{
"attributeId": "888",
"optionId": "bar"
}
]
}
]
},
"paypal-checkout": {
"executePayPalResponse": "",
"orderID": "",
"paymentAction": "CAPTURE",
"paymentID": "",
"paymentMode": "PayPal",
"paypalStatus": ""
},
"shippingAddress": null,
"vouchers": null
},
"deleted": false,
"deliveryStatus": {},
"id": "820",
"isImported": false,
"payedAt": "2024-11-07T17:38:32Z",
"paymentStatus": 1,
"processingStatus": 0,
"subshopId": "deutsch",
"updatedAt": "2024-11-07T17:38:32Z",
"verificationComment": {},
"verificationStatus": 0,
"version": 1
},
...
],
"nextPageToken": "Mw",
"totalCount": 4
}
```
#### Filter fields
`createdAt`, `updatedAt`, `payedAt`, `id`, `subshopId`, `accountId`, `processingStatus`, `paymentStatus`, `verificationStatus`, `deleted`
#### Sort fields
`createdAt`, `updatedAt`, `id`, `processingStatus`, `paymentStatus`, `subshopId`
#### Error codes
| **Error** | **Type** | **Reason** |
| ----------------------- | ------------------- | --------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read users. |
| 400 Bad Request | "invalidValue" | |
| 400 Bad Request | "unknownDataField" | A filter or sort field is invalid. |
| 400 Bad Request | "unknownOperation" | A filter type is invalid. |
| 400 Bad Request | "invalidCharacters" | `size` is not an integer.
A filter value is invalid. |
| 400 Bad Request | "syntaxError" | `sort` contains more than one or no ":". |
| 503 Service Unavailable | "internalError" | Not all orders could be decrypted. |
### GET orders/\{orderId}
This method retrieves the details of a single order by its unique order ID.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/orders/860
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"createdAt": "2024-11-08T14:36:30Z",
"data": {
"billAddress": {
"businessFax": "",
"businessPhone": "",
"city": "asdf",
"company": "",
"country": "DE",
"countryName": "Deutschland",
"custom": null,
"dateOfBirth": "",
"department": "",
"fax": "",
"firstName": "asdf",
"lastName": "asdf",
"mobilePhone": "",
"phone": "987",
"salutationCode": "1",
"salutationText": "Herr",
"state": "",
"street": "asdf",
"streetNumber": "9",
"taxId": "",
"titleCode": "",
"zip": "99999"
},
"computop-hosted": {},
"customer": {
"accountId": 1,
"accountType": "registered",
"email": "root@root.root",
"ipAddress": "172.18.0.1"
},
"dummy": {},
"freeFields": {
"agb.checked": "true",
"agb.merchantText": "agb text here",
"comment.text": ""
},
"general": {
"dateTime": "2024-11-08T14:36:30Z",
"orderId": "860",
"sessionId": "16be344c872261602e84cd0116e0b7a11a...",
"shopId": "myshop",
"shopLanguage": "",
"subshopId": "deutsch",
"testMode": false
},
"order": {
"currencyIso": "EUR",
"currencySymbol": "€",
"defaultTaxRate": "0.1900000",
"delivererId": "dhl",
"delivererOrderText": "DHL",
"deliveryCost": "11.00",
"deliveryTaxRate": "0.1900000",
"paymentId": "prepayment",
"paymentOrderText": "Vorauskasse",
"priceType": "gross",
"subtotal": "8.00",
"tax": "1.76",
"total": "19.00",
"totalCommission": "0.00",
"totalDiscount": "0.00",
"totalVoucher": "0.00"
},
"orderList": {
"item": [
{
"basketId": "01ddd733642b89429105",
"isAutoBasket": false,
"isChangeable": true,
"isRemovable": true,
"isVisible": true,
"itemNumber": "123456",
"name": "Tartan-Langarm-Polo in Navy",
"price": "8.00",
"productId": "106-19021",
"quantity": "1.00",
"singleTotal": "8.00",
"taxId": "zero",
"taxRate": "0.0000000",
"total": "8.00",
"variantId": "",
"variantSelection": null
}
]
},
"paypal-checkout": {
"executePayPalResponse": "",
"orderID": "",
"paymentAction": "CAPTURE",
"paymentID": "",
"paymentMode": "PayPal",
"paypalStatus": ""
},
"shippingAddress": null,
"vouchers": null
},
"deleted": false,
"deliveryStatus": {},
"id": "860",
"paymentStatus": 1,
"processingStatus": 0,
"subshopId": "deutsch",
"verificationComment": {},
"verificationStatus": 0
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ----------------------- | --------------- | --------------------------------------------------------------------------- |
| 401 Unauthorized | | You are not an administrator and do not have permission to read order data. |
| 404 Not Found | | The order was not found. |
| 400 Bad Request | "missing" | `orderId` is missing. |
| 503 Service Unavailable | "internalError" | The order could not be loaded or decrypted. |
### PUT orders/\{orderId}
This method updates an existing order by its unique order ID. All fields are optional. The `deliveryStatus` field should be an object serialized as a string. The fields `verificationComment` (String) and `verificationTitle` (String) are only evaluated when the `verificationStatus` is changed.
Whenever the verification status is changed, a log entry with log level `Info` and message ID `order.updateVerificationStatusSuccess` is automatically created.
Values for `processingStatus`:
`0 = New`\
`1 = Finished`\
`2 = Deleted`\
`3 = Canceled`
Values for `verificationStatus`:
`0 = Default`\
`1 = Test`\
`2 = Fake`\\
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/orders/188
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"processingStatus": 3,
"verificationStatus": 2,
"verificationComment": "Mein Kommentar",
"verificationTitle": "Mein Titel",
"deliveryStatus": "{\"type\":\"global\",\"statusType\":\"tracking\",\"data\":{\"trackingVendorId\":\"\",\"trackingNumber\":\"12345\"}}"
}
```
#### Response
On success, the updated order is returned (same format as for GET orders/\{orderId}).
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"id": "188",
"subshopId": "deutsch",
"data": { ... },
"createdAt": "2025-04-16T13:02:43Z",
"processingStatus": 3,
"paymentStatus": 1,
"deleted": false,
"deliveryStatus": { ... },
"verificationComment": {},
"verificationStatus": 2
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ----------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read users. |
| 400 Bad Request | | Request body could not be loaded.
Updating failed. |
| 400 Bad Request | "unknownDataField" | An attempt was made to update an unknown field. Allowed fields: `processingStatus`, `verificationStatus`, `deliveryStatus`, `verificationComment`, `verificationTitle`. |
| 400 Bad Request | "invalidFormat" | `processingStatus` is not a number. `verificationStatus` is not a number. `deliveryStatus`, `verificationComment`, or `verificationTitle` is not a string. |
| 400 Bad Request | "invalidValue" | `processingStatus` ∉ \[0;3]
`verificationStatus` ∉ \[0;2] |
| 400 Bad Request | "illegalOperation" | |
| | 404 Not Found | |
| 503 Service Unavailable | "internalError" | The order could not be reloaded after the update. |
### DELETE orders/\{orderId}
This method deletes an existing order by its unique order ID.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/orders/265
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ----------------------- | --------------- | ----------------------------------------------------------------------------- |
| 401 Unauthorized | | You are not an administrator and do not have permission to delete order data. |
| 400 Bad Request | "missing" | `orderId` is missing. |
| 404 Not Found | | The order was not found. |
| 503 Service Unavailable | "internalError" | The order could not be loaded or decrypted. |
## Support
For technical questions and assistance, our support team is available to you: [To the customer portal](https://websale.atlassian.net/servicedesk/customer/portal/6)
Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)
Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.