Order insertion

Request

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

Security

shoptetAccessToken or shoptetPrivateApiToken

Query

suppressDocumentGenerationboolean

suppress the generation of linked documents.

Default:false

Example:suppressDocumentGeneration=true

suppressEmailSendingboolean

suppress sending the linked information e-mails.

Default:false

Example:suppressEmailSending=true

suppressProductCheckingboolean

suppress the product existence check as per code and GUID

Default:false

Example:suppressProductChecking=true

suppressStockMovementsboolean

suppress deduction of the products from stock

Default:false

Example:suppressStockMovements=true

suppressHistoricalMandatoryFieldsboolean

set the flag that disables mandatory fields checking

Default:false

Example:suppressHistoricalMandatoryFields=true

suppressHistoricalPaymentCheckingboolean

set the flag that paymentMethodGuid can be null

Default:false

Example:suppressHistoricalPaymentChecking=true

suppressHistoricalShippingCheckingboolean

set the flag that shippingGuid can be null

Default:false

Example:suppressHistoricalShippingChecking=true

Content-Typestringrequired

Default:"application/json"

Bodyapplication/json

dataobject(orderCreate)required

curl -i -X POST \
  'https://api.docs.shoptet.com/_mock/shoptet-api/openapi/api/orders?suppressDocumentGeneration=true&suppressEmailSending=true&suppressProductChecking=true&suppressStockMovements=true&suppressHistoricalMandatoryFields=true&suppressHistoricalPaymentChecking=true&suppressHistoricalShippingChecking=true' \
  -H 'Content-Type: application/json' \
  -H 'Shoptet-Access-Token: YOUR_API_KEY_HERE' \
  -d '{
    "data": {
      "creationTime": "2018-01-21T14:15:47+0100",
      "code": "2024-123",
      "language": "cs",
      "externalCode": "X123",
      "cashDeskOrder": true,
      "statusId": -1,
      "sourceId": -1,
      "salesChannelGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
      "email": "foo@bar.cz",
      "phone": "+420123456789",
      "birthDate": "1990-01-01",
      "vatPayer": true,
      "paymentMethodGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
      "shippingGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
      "shippingDetails": null,
      "paid": true,
      "billingMethodCode": 2,
      "clientIPAddress": "62.128.123.12",
      "customerGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
      "billingAddress": {
        "company": "Smith & Smith",
        "fullName": "John Doe",
        "street": "Main Street",
        "streetWithNr": "Main Street 123",
        "houseNumber": "123",
        "city": "Flat Country",
        "district": "Bohemia",
        "additional": "3rd floor",
        "zip": "123 00",
        "countryCode": "CZ",
        "regionName": "Central Bohemia",
        "regionShortcut": "SC",
        "companyId": "123456",
        "vatId": "CZ123456",
        "taxId": "CZ123456"
      },
      "addressesEqual": true,
      "deliveryAddress": null,
      "notes": null,
      "stockId": 1,
      "currency": {
        "code": "CZK",
        "exchangeRate": "1.0000"
      },
      "vatMode": "Normal",
      "items": [
        {
          "itemType": "product",
          "name": "Large chocolate",
          "variantName": "Dark chocolate",
          "brand": "Willy Wonka",
          "supplierName": "Dodavatel s.r.o.",
          "productGuid": "1b02cb8e-d7b5-11e0-9a5c-feab5ed617ed",
          "code": "123-456",
          "remark": "With cubicles",
          "warrantyDescription": "2 years",
          "amountCompleted": "1.000",
          "additionalField": "TO BALÍKOVNA, Karlínské náměstí 145/1, Karlín, 18600, Prague",
          "amount": "1.000",
          "amountUnit": "ks",
          "weight": "100",
          "priceRatio": "0.7",
          "vatRate": "21.00",
          "itemPriceWithVat": "121.00",
          "itemPriceWithoutVat": "100.00",
          "unitPriceWithVat": "121.00",
          "unitPriceWithoutVat": "100.00",
          "buyPriceWithVat": "121.00",
          "buyPriceWithoutVat": "100.00",
          "buyPriceVatRate": "21.00",
          "statusId": -1,
          "recyclingFeeId": 2,
          "surchargeParameters": [
            {
              "parameterCode": "surchargeCode",
              "valueIndex": "high",
              "price": "21.00"
            }
          ],
          "consumptionTaxId": 1
        }
      ]
    }
  }'

Responses

Created

Bodyapplication/json

dataobjectrequired

errorsArray of objects or null(Errors)required

metadataobject(Metadata)required

Response

{
  "data": {
    "order": { … }
  },
  "errors": [
    { … }
  ],
  "metadata": {
    "requestId": "019c8c34-64f3-7328-af43-bf1e34fa39d7"
  }
}

Order insertion

Request

Query

Headers

Responses

Was this helpful?