# 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 ?itemsPerPage=100, 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 (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 orderCodes 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 accepts max. 50 order codes in request 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): { "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](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 /api/orders/ endpoint. Please note following rules - code .. maxLength 10 characters - email .. maxLength 100 characters - phone .. maxLength 32 characters - externalCode .. maxLength 255 characters - billingAddress.company .. maxLength 255 characters - billingAddress.fullName .. maxLength 255 characters - billingAddress.street .. maxLength 255 characters - billingAddress.houseNumber .. maxLength 255 characters - billingAddress.city .. maxLength 255 characters - billingAddress.district .. maxLength 255 characters - billingAddress.additional .. maxLength 255 characters - billingAddress.zip .. maxLength 255 characters - billingAddress.regionName .. maxLength 255 characters - billingAddress.regionShortcut .. maxLength 255 characters - billingAddress.companyId .. maxLength 18 characters - billingAddress.vatId .. maxLength 16 characters - billingAddress.taxId .. maxLength 16 characters - deliveryAddress.company .. maxLength 255 characters - deliveryAddress.fullName .. maxLength 255 characters - deliveryAddress.street .. maxLength 255 characters - deliveryAddress.houseNumber .. maxLength 255 characters - deliveryAddress.city .. maxLength 255 characters - deliveryAddress.district .. maxLength 255 characters - deliveryAddress.additional .. maxLength 255 characters - deliveryAddress.zip .. maxLength 255 characters - deliveryAddress.regionName .. maxLength 255 characters - deliveryAddress.regionShortcut .. maxLength 255 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 ## 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. See Order snapshot schema for more details. This endpoint has several sections, which are exported only when requested in the include parameter (see Section on demand). Include parameter | Meaning --- | --- notes | 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. images | Order images shippingDetails | Transport details stockLocation | Position in the stock surchargeParameters | Item surcharge parameters productFlags | Item product flags Use orderCodes 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 accepts max. 50 order codes in request 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 include parameter (see Section on demand). Value | Section --------|------ notes | 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. images| Order images shippingDetails| Transport details stockLocation| Position in the stock surchargeParameters| Item surcharge parameters paymentTransactions| Payment transactions within the order productFlags| Item product flags Returns the detail for one order. In the items 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. productGuid item contains GUID of purchased product. If this is changed or deleted, the order is not affected. You have to take into account that productGuid does not have to refer to an existing product. The same goes for the code item, containing the identification of a purchased variant or product. You have to take into account that when deleting the product or changing the code of the product, the reference from the order is lost. In other words, you have to take into account the fact that the code or productGuid do not have to refer to one of the currently existing products (variant). They may also be null. 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 displayPrices, which contains the presentation (printout) version of each item. If you state the include=images 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 shippingDetails section, there is an information about shipping the order. branchId is used for the identification of the carrier's branch and next fields are used for the detail of the branch (name, address, etc.). carrierId is used for the numeral identification of the carrier. Nowadays this field is used for Zasilkovna only and the value can be null 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. Please note following rules - email .. maxLength 100 characters - phone .. maxLength 32 characters - billingAddress.company .. maxLength 255 characters - billingAddress.fullName .. maxLength 255 characters - billingAddress.street .. maxLength 255 characters - billingAddress.houseNumber .. maxLength 255 characters - billingAddress.city .. maxLength 255 characters - billingAddress.district .. maxLength 255 characters - billingAddress.additional .. maxLength 255 characters - billingAddress.zip .. maxLength 255 characters - billingAddress.regionName .. maxLength 255 characters - billingAddress.regionShortcut .. maxLength 255 characters - billingAddress.companyId .. maxLength 18 characters - billingAddress.vatId .. maxLength 16 characters - billingAddress.taxId .. maxLength 16 characters - deliveryAddress.company .. maxLength 255 characters - deliveryAddress.fullName .. maxLength 255 characters - deliveryAddress.street .. maxLength 255 characters - deliveryAddress.houseNumber .. maxLength 255 characters - deliveryAddress.city .. maxLength 255 characters - deliveryAddress.district .. maxLength 255 characters - deliveryAddress.additional .. maxLength 255 characters - deliveryAddress.zip .. maxLength 255 characters - deliveryAddress.regionName .. maxLength 255 characters - deliveryAddress.regionShortcut .. 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 423 Locked 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 trackingNumber cannot be longer than 32 characters. Please note that additionalField 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 paid to false, the order status will be carried out and the paid value set to false. 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 ?suppressEmailSending=true parameter. Similarly, sending information SMS messages when the order is changed (if set) can be suppressed with the ?suppressSmsSending=true 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 ?suppressDocumentGeneration=true 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 data field you can find the order details and in the errors array eventually details about the failed documents generation. The error code is document-not-generated. Example of an error message: "errors": [ { "errorCode": "document-not-generated", "message": "Delivery note belonging to order \"2020000149\" was not created. Generating document code failed.", "instance": "2020000149" } ] ## 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 - all - copy the order with all its items - no-billing-shipping - copy the order without billing and shipping items - contact-only - 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 order-duplication-stock-overflow. You can use include parameter to include additional parts of response, same as in GET 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 edit action. So, when there is a new item created, it will be displayed like edit action. Endpoint supports Paging. ## Orders with product claims - [GET /api/orders/claims](https://api.docs.shoptet.com/shoptet-api/openapi/orders/getorderclaims.md): Endpoint listing all ordered products with unfulfilled claims. Endpoint supports Paging. ## Order BATCH insertion - [POST /api/orders/batch](https://api.docs.shoptet.com/shoptet-api/openapi/orders/orderbatchinsertion.md): Beta/Experimental feature: This endpoint is currently in beta and may exhibit unexpected behavior. 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 resultUrl in the response. Instead, you can check the attribute log 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 settings and data. The settings parameter: Default suppress params for each row can be defined in URL params same as in Order insertion endpoint. In the settings parameter, you can modify suppress parameters for specific row/record. All params in settings can be in 3 states: - true - _true_ value is applied. - false - _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 false. The data parameter: Structure of the data parameter is the same as the structure of JSON for single Order insertion endpoint. See Order batch create schema for more details. 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).