Creating an order

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:

Example request

{
    "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"
            }
        ]
    }
}

Sending a house number

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.

Different item types

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.

Suppress parameters

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.

Example of a minimum order

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"
}

Cash desk orders

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:

• The customer’s e-mail is not required.
• Shipping and payment items do not need to be included.
• The order must contain at least one product.

Order and item statuses

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)

Product information tracking and existence check

For each order item with a specified code attribute, the system attempts to find the corresponding product in the e-shop database.

• If the item exists, the system automatically adds any missing details (e.g., name, weight, manufacturer, warranty).
• If the item does not exist, the system returns an error, indicating that it cannot find a product with the given 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.

• If you enter an invalid code and productGuid combination, the system will return an error indicating that the provided values are incorrect.

Sample Inputs for Order Creation

Regular product

{
  "itemType":"product",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"
}

Second-hand product

{
  "itemType":"bazar",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"
}

Service

{
  "itemType":"service",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"
}

Gift

{
  "itemType":"gift",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "0.00",  # Gift is free
  "priceRatio": "0.0000"
}

Product set

{
  "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.

• When creating an order, the system verifies that the product set exists and automatically adds its components.
• If you are importing historical orders, you can override this check using suppressProductChecking=true.
• In this case, an unknown product set will be treated as a regular product with the specified price.

Discount coupons

Discount coupon for percentage discount

{
  "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"
}

Discount coupon for specific amount (products with one VAT rate)

{
  "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.
}

Free shipping discount coupon

{
  "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.
}

Discount (e-shop operator adds it in administration)

{
  "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"
}

Discount coupon, discount and various VAT rates

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.