The order creation endpoint will allow you to place a new order in Shoptet. The main use is to import old orders from other systems, or place an order that was created in another system (e.g. via Heureka). The endpoint is quite complex due to the number of items, validations and the variability of e-shops, so we are describing it in a separate article.
For a detailed description of endpoints, please refer to Documentation. Pay particular attention to the description of the available request items, including their format and default values (look for “Request” and “Attributes” in the right pane).
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 large number of order attributes are optional or have their default values – please refer to the documentation for this information. Some items (invoicing and shipping addresses and contact details) are mandatory or optional, depending on how it is set in the e-shop – in administration, under “Settings > Customers > Mandatory fields”. This information can be found with Required fields endpoint.
Two options for saving the house number in the address are particularly problematic. Some e-shop operators only have a street field visible and get the shopper to type the number into this field, while others offer street and house number fields. The split fields correspond to street and houseNumber items in the request. If you have only a connected street (street and number in one string), you can use a streetWithNr item in your request (for example “Francouzská 28”) and we will either save it in its entirety, or divide it to the street and number and save it in the correct fields.
Above is an order with one product, a shipping item, and a payment item. Below are examples of what parameters shall be sent to the Shoptet API, when you want to create different variants in the order content.
There are different types of items in the order and here we will show you how to use them correctly to interpret them properly in Shoptet.
You specify an item type with the itemType attribute, which can have the following values:
product – common product, requires attribute code specification. Used most often.bazar – Second hand product, requires code attribute.service Service, requires codeattribute .gift – Gift, requires code attribute.product-set – Product set, requires code attribute.billing – Payment, you will indicate the price of the order. Do not fill in the code attribute, the payment type is determined by paymentMethodGuid in the data section. The form of the payment is determined by billingMethodCode in the data section (1 = cash on delivery, 2 = wire transfer, 3 = cash, 4 = card).shipping – Transport, you will indicate the price in the order items. Do not fill in the code attribute, the transport type is determined by shippingGuid in the data section. For collection at the Czech Post Office, Zásilkovna and similar, specify the place of collection in the shippingDetails.branchId field.discount-coupon – discount coupon. Do not fill in the code attribute. Individual examples of different discounts are described below.volume-discount – Discount. Do not fill in the code attribute. Individual examples of different discounts are described below.gift-certificate – Gift certificate. Historical item type, do not use.generic-item – General item. Historical item type, do not use.Product, bazar, service, and gift flags do not affect the status of the product in the order, therefore we do not check if the product type in the database matches the type submitted.
The minimum order with delivery must contain three items: shipping, payment, and purchased goods. Each order item must contain at least the attributes of itemType, vatRate and one data of either itemPriceWithVat or itemPriceWithoutVat. Prices shall be given as unit prices.
Some additional fields – billing address, shipping address, contact information – may be set as mandatory, based on the e-shop settings (Administration > Customers > Mandatory fields).
{
"itemType":"shipping",
"vatRate":"21.00",
"itemPriceWithoutVat": "100.00"
}
The Shoptet system can also be used as a store cash desk. In this case, the system generates orders without separate shipping and payment items. You can also create an order from the cash desk via the API. In this case, send "cashDeskOrder": true in the data field and the order will be created in cash desk mode. In this mode, you do not need to enter the customer’s e-mail in the order, and there is no need to include shipping and payment for the order items. In cash desk mode, within order items, you only need to have the products sold (at least one item).
In the Shoptet system, each order and its individual items have their statuses. These statuses may vary. The basic order statuses are common to all e-shops, but each e-shop can define additional custom statuses according to its needs. For a list of order statuses, see API in the endpoint /api/orders/statuses.
You can specify the status of both the order and the individual items via API. This is the statusId attribute. The order status may or may not be written into order items, so we will analyze its behavior in detail later.
In the endpoint /api/orders/statuses response you will find the defaultStatus attribute, which will be marked as the default status later on. The changeOrderItems attribute for each status will be important for our case. This attribute specifies whether the order status should be automatically written to all items. For our example, we imagine that from the order status list, we will get the following answer (simplified):
{
"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) |
The system tries to search the current e-shop database for each order item with the code attribute specified. If the item is found, the system adds any missing parameters to the item based on the information found (name, weight, manufacturer, warranty). If the item is not found, it ends with an error, that it does not know the item with a specific code. If you also need to create the items that do not exist in the e-shop, you can override the existence check with the GET parameter suppressProductChecking=true.
The order item is clearly identified by means of code. However, you can also specify the more detailed productGuid, that defines to which product the code belongs. This information serves for more accurate tracking only. Therefore, if you enter an invalid combination of code and productGuid, you will receive information about an invalid code or productGuid only.
{
"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", # Present is free
"priceRatio": "0.0000"
}
{
"itemType":"product-set",
"code": "32/ZEL",
"vatRate":"21.00",
"itemPriceWithoutVat": "300.00"
}
The product set must be traceable in the database, where we add the contents of the product set. When you import the historical orders, you can override this check by using the suppressProductChecking=true, in which case an unknown product set is placed in the order, as a regular product with a corresponding price.
{
"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"
},
{
"iptemType":"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"
}
Send the discount coupon with any VAT rate and again with 0.00. In the order detail in the e-shop administration, the order is automatically shown with discounts broken down to different VAT rates.