# Orders Basic endpoints for managing orders. See the sections below for other specific actions. ## List of orders - [GET /api/orders](https://api.docs.shoptet.com/shoptet-api/openapi/orders/getlistoforders.md): List of orders in e-shop and cash desks. Endpoint supports Paging. For default calls, it returns 50 orders, using the parameter , you can request up to 100 orders at a time. Temporarily disabled, only 50 orders per page is supported. We apologize for the inconvenience. The list can be filtered according to status, transport, payment, date of creation, order number and customer number. The code () is the order identifier. Although this is usually a number, it is necessary to take into account that this might also include letters, dash, etc. Use request parameter to get the list of specific orders. Order codes are separated by a comma. If you use this query parameter, other filters are not applied, and the set of particular orders is returned. Please note that this parameter . ## Order insertion - [POST /api/orders](https://api.docs.shoptet.com/shoptet-api/openapi/orders/createorder.md): 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): Whether the field is mandatory, apart from the basic definition, also depends on whether the order was created via the cash desk () 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 ). When the order is created, it is checked, whether the e-shop includes products with the respective code (can be suppressed with GET parameter ), the products from the order are deducted from the stock (can be suppressed with the GET parameter ), documentation is created for the order (can be suppressed with the GET parameter ), a confirmation e-mail is sent (can be suppressed with the GET parameter ) and a webhook is executed for the new order. Parameters and 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 can be used to disable mandatory fields checks, but only for "historical" orders ( 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 and allow corresponding field ( and/or ) to be . In that case, if an billing/shipping item is provided in list, 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 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 ). 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 . We will internally convert it to the correct format to be compatible with eshop statistics calculations. Because of the conversion, the value of 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 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](https://developers.shoptet.com/api/documentation/creating-order/) 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 endpoint. - .. maxLength 10 characters - .. maxLength 100 characters - .. maxLength 32 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 18 characters - .. maxLength 16 characters - .. maxLength 16 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 32 characters - .. maxLength 250 characters - .. maxLength 128 characters - .. maxLength 64 characters - .. maxLength 255 characters - .. maxLength 64 characters - .. maxLength 255 characters - .. maxLength 16 characters ## List of all orders - [GET /api/orders/snapshot](https://api.docs.shoptet.com/shoptet-api/openapi/orders/getlistofallorders.md): Using this endpoint, you can get list of all orders with detailed info of each order (like in Order Detail endpoint) asynchronously. See how Asynchronous requests work on our developer's portal. The list may be filtered by date of creation and order code. The code is the order identifier. Although this is usually a number, it is necessary to take into account that this might also include letters, dash, etc. Response will be in jsonlines format with each order taking one line of output file. One order in response has the same format as order detail response (in attribute) This endpoint has several sections, which are exported only when requested in the parameter (see Section on demand). Include parameter | Meaning --- | --- | Order remarks, including up to six additional fields, which can be freely used by e-shop for its individual needs. The field names can be defined in administration and this section returns their names. | Order images | Transport details | Position in the stock | Item surcharge parameters | Item product flags Use request parameter to get the list of specific orders. Order codes are separated by a comma. If you use this query parameter, other filters are not applied, and the set of particular orders is returned. Please note that this parameter . Result file is compressed using GZIP. ## Order detail - [GET /api/orders/{code}](https://api.docs.shoptet.com/shoptet-api/openapi/orders/getorderdetail.md): This endpoint has several sections, which are only sent when requested in the parameter (see Section on demand). Value | Section --------|------ | Order remarks, including up to six additional fields, which can be freely used by e-shop for its individual needs. The field names can be defined in administration and this section returns their names. | Order images | Transport details | Position in the stock | Item surcharge parameters | Item product flags Returns the detail for one order. In the field, the individual items of the order, including transport and payment methods. The product name and variants, weight, manufacturer and similar items are copied into the order items when the order is made. Even though the products are changed later in the shop, the orders are not affected. item contains GUID of purchased product. If this is changed or deleted, the order is not affected. You have to take into account that does not have to refer to an existing product. The same goes for the item, containing the identification of a purchased variant or product. You have to take into account that when deleting the product or changing the of the product, the reference from the order is lost. In other words, you have to take into account the fact that the or do not have to refer to one of the currently existing products (variant). They may also be . In most cases the items in the response are the same as you can see in the administration of PDF printout of an order. There are however some advanced cases (in case of coupon discount with absolute value or in case of a volume discount and products with multiple VAT rates in the order), in which case they are different: - Administration and PDF will show multiple rows for the discount – for each VAT rate one row and the price field split evenly. - The API response will return only one row indicating the total price of the discount. The difference is based on how data is internally stored and presented. The API is bases more on internal storage principle, there is however also an array , which contains the presentation (printout) version of each item. If you state the parameter within the URL, the information about the main image for all products in the order will also be part of the response. For more information about access to images go to Product images. In the section, there is an information about shipping the order. is used for the identification of the carrier's branch and next fields are used for the detail of the branch (name, address, etc.). is used for the numeral identification of the carrier. Nowadays this field is used for Zasilkovna only and the value can be for Czech Zasilkovna or integer for Zasilkovna in the other countries. ## Order deletion - [DELETE /api/orders/{code}](https://api.docs.shoptet.com/shoptet-api/openapi/orders/deleteorder.md) ## Order head change - [PATCH /api/orders/{code}/head](https://api.docs.shoptet.com/shoptet-api/openapi/orders/updateorderhead.md): You can change basic info (head) of order with this method. - .. maxLength 100 characters - .. maxLength 32 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 18 characters - .. maxLength 16 characters - .. maxLength 16 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters - .. maxLength 255 characters ## Download order as PDF - [GET /api/orders/{code}/pdf](https://api.docs.shoptet.com/shoptet-api/openapi/orders/downloadorderaspdf.md): You can request the order as PDF file, response will be as application/octet-stream. You can download pdf documents only one-by-one for every e-shop. Parallel requests end with error. ## Update remarks for the order - [PATCH /api/orders/{code}/notes](https://api.docs.shoptet.com/shoptet-api/openapi/orders/updateremarksfororder.md): The endpoint enables the remarks and additional fields (index 1 - 6) to be updated for the order. Within a call, the update of more data can be called for. The individual data object keys are not optional. Only the key values, which are included in the data object, will be updated. If "customerRemark", "trackingNumber", "eshopRemark" have a value of NULL, the originally saved value will be deleted. For additional fields ("additionalFields” key) only the fields included in this field are updated. If the key value is "text" for NULL additional field, the originally saved text in this field will be deleted. If the non-existing key is entered, or the call is erroneous in another way, no item is updated. Please note that cannot be longer than 32 characters. Please note that with index 1, 2 & 3 cannot be longer than 255 characters. ## Update of order status - [PATCH /api/orders/{code}/status](https://api.docs.shoptet.com/shoptet-api/openapi/orders/updateorderstatus.md): The endpoint enables the order status, “paid” flag and payment method to be updated. This data must be set during a call. All the fields to be updated are optional, but at least one has to be specified. If the key value is "text" for NULL additional field, the originally saved text in this field will be deleted. If a non-existing key is entered, or the call is erroneous in another way, no item is updated. If you call the status setting within your request, which has "set the order as paid" in the definition, and at the same time you required a change of to , the order status will be carried out and the value set to . If the status definition includes sending an e-mail, such an e-mail will be sent. If not required, sending an e-mail can be suppressed with the parameter. Similarly, sending information SMS messages when the order is changed (if set) can be suppressed with the parameter. In analogy, if the status includes document generation (for example a proforma invoice), the document will be generated (if not existent). The generation can be suppressed with the parameter. This endpoint tries not to unnecessarily change the order status. If you try to set the status that the order already has, no change is done and no document is generated. When calling the same requests in parallel, there is the risk that there may be concurrence and related actions may be executed twice. Therefore we recommend calling this request from one source only, in a serial manner. Order status change might imply automatic documents (e. g. invoice) generation. In exceptional cases the generation might fail, although the order status itself gets actually changed. In such case the API return status code 200 (OK), but in the field you can find the order details and in the array eventually details about the failed documents generation. The error code is . Example of an error message: ## Order copy - [POST /api/orders/{code}/copy](https://api.docs.shoptet.com/shoptet-api/openapi/orders/ordercopy.md): This endpoint allows you to copy a order identified by its code. You can choose scope in which will be the order copied. The scope can be - - copy the order with all its items - - copy the order without billing and shipping items - - copy the order without any items Please note, that copy order creates stock demand (if stock module is active and negative stock amount is not allowed) and if this demand overflows the stock, the order will be fully created with error . You can use parameter to include additional parts of response, same as in order detail, to retrieve more information about the copied order in copy response. ## List of order statuses - [GET /api/orders/statuses](https://api.docs.shoptet.com/shoptet-api/openapi/orders/getlistoforderstatuses.md): Detailed information on order status within the e-shop. ## List of order sources - [GET /api/orders/sources](https://api.docs.shoptet.com/shoptet-api/openapi/orders/getlistofordersources.md): Detailed information on current possible order sources within the e-shop. ## Last order changes - [GET /api/orders/changes](https://api.docs.shoptet.com/shoptet-api/openapi/orders/getlastorderchanges.md): The Endpoint is intended to determine the changes after you have loaded the complete list of orders and you need to know, if any of these has been changed (or deleted). Guaranteed history is 30 days, the older data are deleted progressively. Each order in the log is only mentioned with its last change. For example, if the order was modified and then deleted, the log will only show information about its deletion. Can be filtered by changeType = edit/delete parameter. Creation is considered as action. So, when there is a new item created, it will be displayed like action. Endpoint supports Paging. ## Order BATCH insertion - [POST /api/orders/batch](https://api.docs.shoptet.com/shoptet-api/openapi/orders/orderbatchinsertion.md): This endpoint allows you to create multiple orders at once. Batch insertion is processed asynchronously in the same way as, for example, List of all orders, but it does not have in the response. Instead, you can check the attribute which contains successfully created orders and errors. See how Asynchronous requests work on our developer's portal. File with data for insert must be in JSONL (jsonlines) format. Each line must contain one order in JSON format. Maximum size of file is 100MB. The base structure of a JSON row contains 2 main parameters and . Default suppress params for each row can be defined in URL params same as in Order insertion endpoint above. In the parameter, you can modify suppress parameters for specific row/record. - - _true_ value is applied. - - _false_ value is applied. - _parameter is missing_ - The value from corresponding request parameter is used, if corresponding request parameter is not defined the value is set to . - : (, _optional_) - Suppress the generation of linked documents. - : (, _optional_) - Suppress sending the linked information e-mails. - : (, _optional_) - Suppress the product existence check as per code and GUID. - : (, _optional_) - Suppress deduction of the products from stock. - : (, _optional_) - Set the flag that disables mandatory fields checking. - : (, _optional_) - Set the flag that can be . - : (, _optional_) - Set the flag that can be . Structure of the parameter is the same as the structure of JSON for single order insertion above. * For better understanding, see the example of one record bellow ( _The example is formatted for better readability. For common use, it needs to be compressed on one line_): The asynchronous job processes the JSONL file row by row and tries to validate and save the data. If there is any error, the row is skipped and the error is logged, but it does not stop the processing of other rows. In the log, every order is identified by its position in the file (starting from 1).