The order creation endpoint allows you to place a new order in Shoptet. Its primary purpose is to import old orders from other systems or to register an order created in another system (e.g., via Heureka). This endpoint is relatively complex due to the number of items, validations, and the variability of e-shops.
For a detailed description of the endpoints, please refer to the Documentation. Pay close attention to the available request items, including their format and default values (see “Request” and “Attributes” in the right pane).
A large number of order attributes are optional or have default values—please refer to the documentation for details. Some items, such as invoicing and shipping addresses or contact details, may be mandatory or optional, depending on the e-shop’s settings. You can configure these in the administration under Settings > Customers > Mandatory fields. For more details, see the Required fields endpoint.
A typical simple order can be created by calling POST /api/orders with the following content:
{
"data": {
"email": "foo@bar.cz",
"externalCode": "123",
"paymentMethodGuid": "6f2c8e36-3faf-11e2-a723-705ab6a2ba75",
"shippingGuid": "8921cdc1-051b-11e5-a8d3-ac162d8a2454",
"billingAddress": {
"fullName": "Jan Novák",
"street": "Rovná",
"city": "Rovina",
"zip": "12300"
},
"currency": {
"code": "CZK"
},
"items": [
{
"itemType": "product",
"code": "32/ZEL",
"vatRate": "21.00",
"itemPriceWithVat": "121.00"
},
{
"itemType": "billing",
"name": "Wire payment",
"vatRate": "21.00",
"itemPriceWithVat": "0"
},
{
"itemType": "shipping",
"name": "PPL",
"vatRate": "21.00",
"itemPriceWithVat": "59.00"
}
]
}
}
A particular challenge is the two possible ways of storing house numbers in addresses. Some e-shop operators provide only a single street field, requiring customers to enter the house number within it, while others offer separate fields for street and house number.
In the request, these separate fields correspond to street and houseNumber. If you only have a combined street and house number (both in a single string), you can use the streetWithNr field (e.g., “Francouzská 28”). We will then either store it as a whole or split it into separate street and houseNumber fields as needed.
If you send both street and houseNumber along with streetWithNr, the street and houseNumber fields will take priority.
Above is an example of an order containing one product, a shipping item, and a payment item. The following section provides examples of the parameters you need to send to the Shoptet API when creating different variants of order content.
Orders can contain different types of items, and here we will explain how to use them correctly for proper interpretation in Shoptet.
The itemType attribute specifies the type of item and can have the following values:
product – A standard product. Requires the code attribute. This is the most commonly used type.bazar – A second-hand product. Requires the code attribute.service – A service. Requires the code attribute.gift – A gift. Requires the code attribute.product-set – A product set. Requires the code attribute.billing – A payment. Specifies the order’s total price. The code attribute is not used. The payment type is determined by paymentMethodGuid in the data section. The payment method is set via billingMethodCode (1 = cash on delivery, 2 = wire transfer, 3 = cash, 4 = card).shipping – A shipping method. Specifies the shipping cost in the order. The code attribute is not used. The shipping type is determined by shippingGuid in the data section. For collection points (e.g., Czech Post Office, Zásilkovna), specify the pickup location using shippingDetails.branchId.discount-coupon – A discount coupon. The code attribute is not used. Specific discount examples are provided below.volume-discount – A volume discount. The code attribute is not used. Specific discount examples are provided below.The product, bazar, service, and gift item types do not affect the product’s status in the order. Therefore, we do not validate whether the product type in the database matches the submitted type.
When creating an order, we have several suppression parameters that affect the order-saving behavior when set to true.
suppressDocumentGeneration – Suppresses the generation of related documents (e.g., invoices, delivery notes).suppressEmailSending – Suppresses the sending of informational emails related to the order.suppressProductChecking – Suppresses the verification of product existence based on their code and GUID.suppressStockMovements – Prevents the deduction of products from stock when an order is created.suppressHistoricalMandatoryFields – Allows disabling the validation of mandatory fields when creating historical orders.suppressHistoricalPaymentChecking – Allows the paymentMethodGuid value to be null in historical orders.suppressHistoricalShippingChecking – Allows the shippingGuid value to be null in historical orders.A minimum order with delivery must contain three items: shipping, payment, and product. Each order item must include at least the attributes itemType, vatRate, and either itemPriceWithVat or itemPriceWithoutVat. Prices must be specified as unit prices.
Some additional fields—such as billing address, shipping address, and contact information—may be required, depending on the e-shop settings (Administration > Customers > Mandatory fields).
{
"itemType":"shipping",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00"
}
The Shoptet system can also function as a store cash desk, where orders are generated without separate shipping and payment items. You can create a cash desk order via the API by setting "cashDeskOrder": true in the data field.
In this mode:
In the Shoptet system, each order and its individual items have their own statuses, which may vary. The basic order statuses are standard across all e-shops, but each e-shop can define additional custom statuses as needed. For a complete list of order statuses, refer to the API endpoint /api/orders/statuses.
You can set the status of both the entire order and individual items via the API using the statusId attribute. The order status does not necessarily have to be applied to order items, so we will analyze its behavior in more detail later.
The /api/orders/statuses response includes a defaultStatus attribute, which indicates the default status for new orders. Another key attribute is changeOrderItems, which determines whether the order status should be automatically applied to all items.
For example, let’s assume that the response from the order status list provides the following (simplified) output:
"data": {
"defaultStatus": 5,
"statuses": [
{
"id": 1,
"name": "Pending",
"changeOrderItems": true
},
{
"id": 2,
"name": "Packed",
"changeOrderItems": false
},
{
"id": 5,
"name": "New",
"changeOrderItems": false
},
]
}
}
Presume the following request (simplified again):
{
"data": {
"externalCode": "201900232323",
"statusId": "X", # This value will be changed
"items": [
{
"itemType": "product",
"code": "product-A",
"statusId": "2"
},
{
"itemType": "product",
"code": "product-B"
}
]
}
}
Order statuses will then be written as follows (read by lines):
| StatusId of order (X) | product-A | product-B |
|---|---|---|
| null (attribute not specified), default 5 is filled in | 2 | 5 (default) |
1 ("changeOrderItems": true) |
2 | 1 |
2 ("changeOrderItems": false) |
2 | 5 (default) |
5 ("changeOrderItems": false) |
2 | 5 (default) |
For each order item with a specified code attribute, the system attempts to find the corresponding product in the e-shop database.
code.If you need to create items that are not yet in the e-shop, you can bypass the existence check by using the GET parameter suppressProductChecking=true.
Each order item is uniquely identified by its code. Additionally, you can specify productGuid, which links the item to a specific product. This provides more precise tracking but does not affect validation.
code and productGuid combination, the system will return an error indicating that the provided values are incorrect.{
"itemType":"product",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00"
}
{
"itemType":"bazar",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00"
}
{
"itemType":"service",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00"
}
{
"itemType":"gift",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "0.00", # Gift is free
"priceRatio": "0.0000"
}
{
"itemType":"product-set",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "300.00"
}
A product set must be traceable in the database, where its contents are defined.
suppressProductChecking=true.{
"itemType":"product",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00", # Price excl. discount.
"priceRatio": "0.9700" # Coefficient to multiply the price. 3% ~ 0.03 => 0.9700.
},
{
"itemType":"product",
"code": "24-FIA",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00", # Price excl. discount.
"priceRatio": "0.9700" # Coefficient to multiply the price. 3% ~ 0.03 => 0.9700.
},
{
"itemType":"discount-coupon", # We do not send "code” for discount-coupon.
"name": "Discount coupon PROMOTION-SUMMER, discount 3%", # Order item number.
"itemPriceWithoutVat": "0.00", # Discount voucher is free.
"vatRate":"21.00"
}
{
"itemType":"product",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00" # Price before discount.
},
{
"itemType":"product",
"code": "24-FIA",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00" # Price before discount.
},
{
"itemType":"discount-coupon", # We do not send "code” for the discount-coupon.
"name": “Discount coupon PROMOTION-SUMMER-FIX, discount 25 CZK", # Order item number.
"itemPriceWithVat": "-25.00", # The exact amount of the discount is given for the coupon.
"vatRate":"21.00" # Same as vatRate for order items.
}
{
"itemType":"product",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00"
},
{
"itemType":"shipping", # We do not send "code” for shipping.
"vatRate":"21.00",
"itemPriceWithoutVat": "0.00" # Shipping is free.
},
{
"itemType":"discount-coupon", # We do not send "code” for discount-coupon.
"name": “Discount coupon PROMOTION-SHIPPING -Shipping is free", # Order item number.
"itemPriceWithVat": "0.00", # Discount voucher is free.
"vatRate":"21.00" # Same as vatRate for order items.
}
{
"itemType":"product",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00" # Original item price.
},
{
"itemType":"volume-discount", # We do not send "code” for volume-discount.
"name": "Discount", # Order item name.
"itemPriceWithVat": "-45.00", # The operator of e-shop provided an additional discount of 45 CZK.
"vatRate":"0.00"
}
If a discount coupon is applied to an order containing products with different VAT rates, the coupon must be sent twice—once with a VAT rate of 0.00. and once with the applicable VAT rate (e.g., 21.00. ). When the order is processed in the e-shop administration, the Shoptet system automatically distributes the discount across the items according to their respective VAT rates. This ensures correct accounting and a clear breakdown of the discount within the order.