This endpoint enables insert the order into Shoptet, which was created in other system. You can use it for an import
from an older e-shop solution, or to transfer orders from external sales channels.
A large amount of info can be set, but for regular usage only a few attributes are needed. Values of other
attributes are added as per their default values. The detailed information can be found in the right pane, after
clicking on title "Order insertion" above (search for "Request" and "Attributes” sections).
Request is sent in JSON format in its body. Simple example (detailed example can be found in call example in right pane):
{
"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": "Platba převodem",
"vatRate": "21.00",
"itemPriceWithVat": "0"
},
{
"itemType": "shipping",
"name": "PPL",
"vatRate": "21.00",
"itemPriceWithVat": "59.00"
}
]
}
}
Whether the field is mandatory, apart from the basic definition, also depends on whether the order was created via the cash desk
(cashDeskOrder: true) or via e-shop. Some fields from invoicing, delivery and contact data
are mandatory or optional, as per e-shop settings (see also e-shop administration Settings > Customers > Mandatory fields).
When the order is created, it is checked, whether the e-shop includes products with the respective code (can be suppressed with
GET parameter suppressProductChecking=true),
the products from the order are deducted from the stock (can be suppressed with the GET parameter suppressStockMovements=true), documentation is created for the order (can be suppressed with the GET parameter suppressDocumentGeneration=true), a confirmation e-mail is sent (can be suppressed with the GET parameter suppressEmailSending=true) and a webhook is executed for the new order.
**Parameters suppressProductChecking=true and suppressStockMovements=true are to be used only for orders that will not be changed or deleted in the future.
Editing or deleting such an order can damage the consistency of warehousing.**
Parameter suppressHistoricalMandatoryFields=true can be used to disable mandatory fields checks, but only for "historical"
orders (creationTime is older than 24 hours). Keep in mind even historical orders should be kept consistent and complete
as much as possible to allow their processing for statistics, volume calculations etc.
Setting the mandatory items for invoicing and the delivery address can be different between individual e-shops. The mandatory items corresponds to the settings
for ordering from the basket.
Parameters suppressHistoricalPaymentChecking and suppressHistoricalShippingChecking allow corresponding field (paymentMethodGuid and/or shippingGuid)
to be null. In that case, if an billing/shipping item is provided in items list, name field must be filled in that item.
To remove products from the stock, the shop (or product) setting as to whether the inventory can be negative or not is respected.
If a negative value is not permitted for shopping and the order cannot be covered from the current inventory, the order is not created and the API
returns an error message in the errors field.
The order's minimum size or maximum number of items as per the settings of e-shop are not checked.
The endpoint only checks the same parameters as the order detail.
The order can be inserted while using currencies setup in the eshop (see /api/eshop). The exchange rate related to the
eshop default currency is optional. If not provided, the current eshop exchange rate will be used.
For historical orders the exchange rate should be provided using the historical value of the order's creation date.
Shoptet eshops do not store historical exchange rates.
Warning: for SK and CZ different exchange rate format is used. You should use the same form as you get from the endpoint
/api/eshop. We will internally convert it to the correct format to be compatible with eshop statistics calculations.
Because of the conversion, the value of exchangeRate in the response will be different (inverse) to the one you had sent.
When entering the order, the initial welcome e-mail is always sent. Even though the order status is set differently to the initial value,
the e-mail associated with a status change is not sent, but the system welcome e-mail is (to e-shop operator and customer).
When creating the receipt (invoice, proforma invoice, delivery note) the receipt is created with the current date and the 14 days due date, even though
creationTime is given from the past.
Examples of how to work with the order and items statuses, and how to ensure the correct insertion of a discount, can be found in a
separate article at developers.shoptet.com
After the order is successfully created, you will receive a response with a 201 code and a response structure matching the order detail,
which is returned by /api/orders/<code> endpoint.
Please note following rules
code .. maxLength 10 characters
email .. maxLength 100 characters
phone .. maxLength 32 characters
externalCode .. maxLength 255 characters
billingAddress.company .. maxLength 100 characters
billingAddress.fullName .. maxLength 100 characters
billingAddress.street .. maxLength 100 characters
billingAddress.houseNumber .. maxLength 16 characters
billingAddress.city .. maxLength 100 characters
billingAddress.district .. maxLength 64 characters
billingAddress.additional .. maxLength 64 characters
billingAddress.zip .. maxLength 100 characters
billingAddress.regionName .. maxLength 128 characters
billingAddress.regionShortcut .. maxLength 16 characters
billingAddress.companyId .. maxLength 18 characters
billingAddress.vatId .. maxLength 16 characters
billingAddress.taxId .. maxLength 16 characters
deliveryAddress.company .. maxLength 255 characters
deliveryAddress.fullName .. maxLength 64 characters
deliveryAddress.street .. maxLength 100 characters
deliveryAddress.houseNumber .. maxLength 16 characters
deliveryAddress.city .. maxLength 100 characters
deliveryAddress.district .. maxLength 64 characters
deliveryAddress.additional .. maxLength 64 characters
deliveryAddress.zip .. maxLength 100 characters
deliveryAddress.regionName .. maxLength 128 characters
deliveryAddress.regionShortcut .. maxLength 16 characters
notes.trackingNumber .. maxLength 32 characters
items.name .. maxLength 250 characters
items.variantName .. maxLength 128 characters
items.brand .. maxLength 64 characters
items.supplierName .. maxLength 255 characters
items.code .. maxLength 64 characters
items.additionalField .. maxLength 255 characters
items.amountUnit .. maxLength 16 characters
