Place new order with API

With Ecwid API, you can easily place new orders to the store by specifying all their details and sending an API call.

Call the Create order request with order details in JSON format to place a new order.

Create order request does not calculate any order details. Use Calculate order details request before placing an order.

Specify order statuses

You can make a call with both public and secret access tokens.

However, the public_token only allows you to place orders with INCOMPLETE payment status and AWAITING_PROCESSING shipping status.

Use secret_token to place orders with PAID and SHIPPED payment and shipping statuses.

Change customer's number of orders and product stock

Orders placed with API calls automatically change product stock and customer's number of orders if:

• A new order is placed with the PAID payment status

• Order request JSON contains valid product and/or combination IDs.

• Order request JSON contains the customer's email and/or ID.

If a customer with a specified email does not yet exist, the account will be automatically created upon placing an order. The new order will also automatically be assigned to this account.

Request example

The following example is the result of a Calculate order details request:

{
    "refundedAmount": 0,
    "email": "[e-mail]",
    "subtotal": 140,
    "subtotalWithoutTax": 140,
    "total": 154.11,
    "totalWithoutTax": 143.01,
    "giftCardRedemption": 0,
    "totalBeforeGiftCardRedemption": 154.11,
    "giftCardDoubleSpending": false,
    "tax": 11.1,
    "customerTaxExempt": false,
    "customerTaxIdValid": true,
    "b2b_b2c": "b2c",
    "reversedTaxApplied": false,
    "customerRequestedInvoice": false,
    "customerFiscalCode": "",
    "electronicInvoicePecEmail": "",
    "electronicInvoiceSdiCode": "",
    "couponDiscount": 0,
    "paymentStatus": "PAID",
    "fulfillmentStatus": "AWAITING_PROCESSING",
    "orderNumber": 0,
    "vendorOrderNumber": "0",
    "volumeDiscount": 15,
    "membershipBasedDiscount": 0,
    "totalAndMembershipBasedDiscount": 0,
    "customDiscount": [
        14
    ],
    "customSurcharges": [
        {
            "id": "tips",
            "value": 10,
            "type": "PERCENT",
            "total": 14.01,
            "totalWithoutTax": 14.01,
            "description": "",
            "descriptionTranslated": "",
            "taxable": false,
            "taxes": []
        }
    ],
    "discount": 31,
    "usdTotal": 0,
    "createDate": "2025-03-10 11:16:37 +0000",
    "updateDate": "2025-03-10 11:16:37 +0000",
    "createTimestamp": 1741605397,
    "updateTimestamp": 1741605397,
    "items": [
        {
            "id": 0,
            "productId": 689454040,
            "price": 70,
            "priceWithoutTax": 70,
            "productPrice": 50,
            "quantity": 2,
            "shortDescriptionTranslated": {
                "cs": "",
                "en": ""
            },
            "tax": 11.1,
            "shipping": 18,
            "quantityInStock": 0,
            "name": "Best Pizza",
            "nameTranslated": {
                "cs": "",
                "en": "Best Pizza"
            },
            "isShippingRequired": true,
            "weight": 0.5,
            "trackQuantity": false,
            "fixedShippingRateOnly": false,
            "fixedShippingRate": 0,
            "digital": false,
            "productAvailable": true,
            "couponApplied": false,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "32",
                    "valueTranslated": {
                        "cs": "",
                        "en": "32"
                    },
                    "valuesArray": [
                        "32"
                    ],
                    "selections": [
                        {
                            "selectionTitle": "32",
                            "selectionModifier": 20,
                            "selectionModifierType": "ABSOLUTE"
                        }
                    ],
                    "type": "CHOICE"
                }
            ],
            "combinationId": 421616046,
            "taxes": [
                {
                    "name": "10% Tax",
                    "value": 10,
                    "total": 11.1,
                    "taxOnDiscountedSubtotal": 11.1,
                    "taxOnShipping": 0,
                    "includeInPrice": true,
                    "sourceTaxRateId": 947976181,
                    "sourceTaxRateType": "MANUAL",
                    "taxClassCode": "default"
                }
            ],
            "discounts": [
                {
                    "discountInfo": {
                        "id": 25039589,
                        "value": 15,
                        "type": "ABS",
                        "base": "SUBTOTAL",
                        "orderTotal": 10,
                        "appliesToItems": [],
                        "appliesToOrderItems": [],
                        "triggeredByOrderItems": []
                    },
                    "total": 15
                },
                {
                    "discountInfo": {
                        "id": 25039590,
                        "value": 10,
                        "type": "PERCENT",
                        "base": "CUSTOM",
                        "orderTotal": 0,
                        "description": "Custom app discount",
                        "appliesToItems": [],
                        "appliesToOrderItems": [],
                        "triggeredByOrderItems": []
                    },
                    "total": 14
                }
            ],
            "taxable": true,
            "giftCard": false,
            "isCustomerSetPrice": false,
            "attributes": []
        }
    ],
    "refunds": [],
    "shippingPerson": {
        "name": "Mary Watson",
        "firstName": "Mary",
        "lastName": "Watson",
        "companyName": "Best Brownies Inc.",
        "street": "The other street",
        "city": "San Diego",
        "countryCode": "US",
        "countryName": "United States",
        "postalCode": "90001",
        "stateOrProvinceCode": "CA",
        "stateOrProvinceName": "California",
        "phone": "123141321"
    },
    "shippingOption": {
        "shippingMethodId": "6589-1709547151586",
        "shippingMethodName": "Standard shipping",
        "shippingRate": 20,
        "shippingRateWithoutTax": 20,
        "isPickup": false,
        "fulfillmentType": "SHIPPING",
        "isShippingLimit": false
    },
    "availableShippingOptions": [
        {
            "shippingMethodId": "6589-1709547151586",
            "shippingMethodName": "Standard shipping",
            "shippingRate": 20,
            "isPickup": false,
            "fulfillmentType": "SHIPPING",
            "isShippingLimit": false
        },
        {
            "shippingMethodId": "3919-1640004025851",
            "shippingMethodName": "FREE Shipping",
            "shippingRate": 0,
            "isPickup": false,
            "fulfillmentType": "SHIPPING",
            "isShippingLimit": false
        },
        {
            "shippingMethodId": "4959-1595934622523",
            "shippingMethodName": "Pickup",
            "shippingRate": 0,
            "isPickup": true,
            "pickupInstruction": "",
            "fulfillmentType": "PICKUP",
            "isShippingLimit": false
        }
    ],
    "availableTaxes": [
        {
            "id": 947976181,
            "name": "10% Tax",
            "enabled": true,
            "includeInPrice": true,
            "useShippingAddress": true,
            "taxShipping": false,
            "appliedByDefault": true,
            "defaultTax": 10,
            "rules": []
        }
    ],
    "predictedPackage": [],
    "shippingLabelAvailableForShipment": true,
    "shipments": [],
    "additionalInfo": {},
    "paymentParams": {},
    "extraFields": {},
    "discountInfo": [
        {
            "id": 25039589,
            "value": 15,
            "type": "ABS",
            "base": "SUBTOTAL",
            "orderTotal": 10,
            "appliesToItems": [],
            "appliesToOrderItems": [],
            "triggeredByOrderItems": []
        },
        {
            "id": 25039590,
            "value": 10,
            "type": "PERCENT",
            "base": "CUSTOM",
            "orderTotal": 0,
            "description": "Custom app discount",
            "appliesToItems": [],
            "appliesToOrderItems": [],
            "triggeredByOrderItems": []
        },
        {
            "id": 25039591,
            "value": 10,
            "type": "PERCENT",
            "base": "SHIPPING",
            "orderTotal": 50,
            "description": "10% off on cart total above €50,00",
            "appliesToItems": [],
            "appliesToOrderItems": [],
            "triggeredByOrderItems": [],
            "appliesToShippingMethodId": "6589-1709547151586"
        }
    ],
    "ticket": 0,
    "hidden": false,
    "taxesOnShipping": [],
    "disableAllCustomerNotifications": false,
    "externalFulfillment": false,
    "externalOrderData": {},
    "utmDataSets": [],
    "pricesIncludeTax": false
}

Response example

In response, you receive a JSON with order ID and internal order ID (for old apps):

{
    "id": 547872251,
    "orderId": "TL3E4"
}

You can use any of the IDs for API calls. However, we don't recommend sharing the internal ID with customers or store owners, as they can't see it anywhere in Ecwid admin or notifications.