API reference orders - WEBSALE Dokumentation

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)	Shipping address
data.billAddress	Object (Address)	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

{
    "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

https://www.<your-shop>.de/admin/api/v1/orders

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/orders/860

Response

{
    "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

https://www.<your-shop>.de/admin/api/v1/orders/188

Request body

{
    "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}).

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/orders/265

Response

{
    "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 Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Data fields of an order

​Example

​Using the methods

​GET orders

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET orders/{orderId}

​Example

​Response

​Error codes

​PUT orders/{orderId}

​Example

​Request body

​Response

​Error codes

​DELETE orders/{orderId}

​Example

​Response

​Error codes

​Support

Supported methods

Data fields of an order

Example

Using the methods

GET orders

Example

Response

Filter fields

Sort fields

Error codes

GET orders/{orderId}

Example

Response

Error codes

PUT orders/{orderId}

Example

Request body

Response

Error codes

DELETE orders/{orderId}

Example

Response

Error codes

Support