Calculate order details

When you use Create order API call to place a new order in the store, the order is made exactly as you specify it in JSON. But what to do if you need to calculate taxes, fees, discounts, and shipping costs?

This is what the Calculate order detailscall is for. It accepts a cart JSON object and responds with the order JSON object. The resulting object can be instantly used in the Create order call.

Pass cart details

Upon receiving a new request, Ecwid API checks the following cart details to calculate the order:

• Product details: items array for ID, selected options, quantity, wholesale prices, combination ID, and other details of products. Ecwid API doesn't validate product details. You must send product prices in the request, but they can not match the real products from your store.

• Shipping details: shippingPerson/billingPerson objects for delivery address, shippingOption object for shipping costs. Pass the correct shipping method name, ID, and type in the shippingOption object to get rate calculation.

• Tax settings: items’ tax classes, customer’s ID and tax exemption. Store tax settings are automatically added to the request and are used in calculations.

• Discounts/surcharges: gift cards, discount coupons, promotions, and custom surcharges. Ecwid API doesn't validate discount/surcharge details. You can send any discounts/surcharges in the request, even if they don't match the ones from your store.

Request example

{
    "email": "[email protected]",
    "items": [
        {
            "productId": 689454040,
            "price": 70,
            "productPrice": 50,
            "quantity": 2,
            "isShippingRequired": true,
            "name": "Best Pizza",
            "weight": 0.5,
            "combinationId": 421616046,
            "selectedOptions": [
                {
                    "type": "CHOICE",
                    "name": "Size",
                    "value": "32",
                    "selections": [
                        {
                            "selectionTitle": "32",
                            "selectionModifier": 20,
                            "selectionModifierType": "ABSOLUTE"
                        }
                    ]
                }
            ] 
        }
    ],
    "shippingPerson": {
        "name": "Mary Watson",
        "companyName": "Best Brownies Inc.",
        "street": "The other street",
        "city": "San Diego",
        "countryCode": "US",
        "postalCode": "90001",
        "stateOrProvinceCode": "CA",
        "phone": "123141321"
    },
    "shippingOption": {
        "shippingMethodName": "Standard shipping",
        "shippingMethodId": "6589-1709547151586",
        "fulfillmentType": "SHIPPING"
    },
    "discountInfo": [
        {
            "value": 15,
            "type": "ABS",
            "base": "SUBTOTAL",
            "orderTotal": 10
        },
        {
            "value": 10,
            "type": "PERCENT",
            "base": "CUSTOM",
            "description": "Custom app discount"
        }
    ],
    "customSurcharges": [
        {
            "id": "tips",
            "total": 10,
            "totalWithoutTax": 10,
            "value": 10,
            "type": "PERCENT",
            "taxable": false
        }
    ]
}

Receive calculated order details

In the response, you get a JSON with calculated order details, including:

• Taxes (applied automatically)

• Promotions (applied automatically)

• Shipping costs (if request had a valid shipping method)

• Discount coupons (if request had a valid discount coupon)

• Gift card application and balance change (if request had a valid gift card)

• Custom surcharges/discounts (only if passed in the request)

Response example

{
    "id": "0",
    "internalId": 0,
    "refundedAmount": 0,
    "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": "INCOMPLETE",
    "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
}

After receiving a response, remove the "id" and "internalId" fields, and use the resulting JSON in the Place new order with API Place new order with API request.