Calculate order details

This method will calculate and return shipping rates and taxes for the order sent in a request. You can use it for your custom checkout process prior to creating an actual order in the store. Requests to this endpoint don't create any new orders in the actual store. See Shipping and Taxes help articles to find out more information.

Headers

NameTypeDescription
AuthorizationstringoAuth token with mandatory Bearer before it. Example: Bearer e***s0, where e***s0 should be replaced with your oAuth token.

Request

A JSON object of type 'Order' with the following fields:

📘

Parameters in bold are mandatory

Order

FieldTypeDescription
emailstringCustomer email address
ipAddressstringCustomer IP
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information. If no shippingPerson provided, the values are taken from billingPerson
discountInfoArray<DiscountInfo>Information about discounts applied to the order (coupons are not included). If passed ignores discounts set by store owner
giftCardCodestringGift card code to apply to this cart
customSurchargesArray<customSurchargesDetails>Information about applied surcharges
shippingOption<ShippingOptionDetails>Information about selected shipping option. If passed ignores fixedShippingRateOnly and fixedShippingRate fields in OrderItem array
handlingFee<HandlingFeeDetails>Handling fee details. Overwrites the handling fee set by a store admin
paymentOptionsDetails<PaymentOptionsDetails>Information about selected payment option.

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn't belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredbooleantrue/false: shows whether the item requires shipping. If not specified, the value is considered true
trackQuantitybooleantrue/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlybooleantrue/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalbooleantrue/false: shows whether the item has downloadable files attached
couponAppliedbooleantrue/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
dimensions<OrderItemDimensions>Product dimensions info
couponAmountnumberCoupon discount amount applied to item. Provided if discount applied to order. Is not recalculated if cart is updated later manually
discountsArray<OrderItemDiscounts>Discounts applied to order item 'as is'. Provided if discounts are applied to cart (not including discount coupons) and are not recalculated if cart is updated later manually

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping
includeInPricebooleantrue if the tax rate is included in product prices. More details: Taxes in Ecwid

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered option value(s) as a string. For the CHOICES type, provides a string with all chosen values (comma-separated). You can use this to simply print out all selected values.
valuesArrayArraySelected option values as an array. For the CHOICES type, provides an array with the chosen values so you can iterate through them in your app.
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)
selectionsArray<SelectionInfo>Details of selected product options. If sent in update order request, other fields will be regenerated based on information in this field

OrderItemOptionFile

FieldTypeDescription
idnumberFile ID
namestringFile name
sizenumberFile size in bytes
urlstringFile URL

SelectionInfo

FieldTypeDescription
selectionTitlestringSelection title, as set by merchant
selectionModifiernumberSelection price modifier amount. Value is negative for negative modifiers
selectionModifierTypestringPrice modifier type: "PERCENT" or "ABSOLUTE"

OrderItemDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress
citystringCity
countryCodestringTwo-letter country code. Taxes depend on the countryCode field:
  • countryCode is present in the request and has value - tax is calculated depending on the tax settings;
  • countryCode is present and the value is empty (example: "CountryCode": "") - taxes don't apply if taxes in the store are configured for certain countries. In other cases, taxes apply;
  • countryCode is not present (regardless of the other lines in PersonInfo) - taxes don't apply if taxes in the store are configured for certain countries. In other cases, taxes apply.
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name, e.g. New York
phonestringPhone number

OrderItemDiscounts

FieldTypeDescription
discountInfo<OrderItemDiscountInfo>Info about discounts applied to item
totalnumberTotal order item discount value for this discount

OrderItemDiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
orderTotalnumberMinimum order subtotal the discount applies to

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
applicationLimitstringApplication limit for discount coupons. Possible values: "UNLIMITED", "NEW_CUSTOMER_ONLY", "REPEAT_CUSTOMER_ONLY"
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM. If not specified, default value: CUSTOM
orderTotalnumberMinimum order subtotal the discount applies to. Default value: 0
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

customSurchargesDetails

FieldTypeDescription
idstringSurcharge id. If not specified default value: Custom Surcharge
valuenumberSurcharge value
typestringSurcharges type: ABSOLUTE or PERCENT. If not specified default value: ABSOLUTE
descriptionstringSurcharge description. Empty if not specified
taxablebooleanControls tax application for the surcharge. If not specified default value: false

ShippingOptionDetails

FieldTypeDescription
shippingMethodIdstringShipping option id. Unsupported value returns error message Shipping option unavailable or Shipping option not found
shippingMethodNamestringShipping option name. Returns Custom shipping if not specified
shippingRatenumberRate
pickupInstructionstringInstruction for customer on how to receive their products
fulfillmentTypestringSupported values: PICKUP, DELIVERY, SHIPPING. Default value: SHIPPING if not specified

PaymentOptionsDetails

FieldTypeDescription
paymentIdstringPayment option id. If there are surcharges set for the payment option order total will be calculated taking into account the surcharge value.

HandlingFeeDetails

FieldTypeDescription
namestringHandling fee name. If ignored, returns Handling Fee in response
valuenumberHandling fee value
descriptionstringHandling fee description for customer
taxes<HandlingFeeTaxes>Taxes applied to the handling fee

HandlingFeeTaxes

FieldTypeDescription
namestringTax name
valuenumberTax percent value
totalnumberTax total value

Response

A JSON object of type 'Order' with the following fields:

Order

FieldTypeDescription
subtotalnumberOrder subtotal
totalnumberOrder total cost
emailstringCustomer email address
taxnumberTax total
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status, will always be returned as INCOMPLETE
fulfillmentStatusstringFulfilment status, will always be returned as AWAITING_PROCESSING
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
membershipBasedDiscountnumberSum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscountnumberThe sum of discount based on subtotal AND customer group. Is included into the discount field
customSurchargesArray<customSurchargesInfo>Information about applied surcharges
discountnumberThe sum of all applied discounts except for the coupon discount. To get the total order discount, take the sum of couponDiscount and discount field values
usdTotalnumberOrder total in USD
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
createTimestampnumberThe date of order placement in UNIX Timestamp format, e.g 1427268654
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
availableShippingOptionsArray<ShippingOptionInfo>All calculated shipping methods for this order (excluding methods where minimumOrderSubtotal value is above the order subtotal)
availableTaxesArray<TaxInfo>All calculated taxes for this order
handlingFee<HandlingFeeInfo>Handling fee details
predictedPackageArray<PredictedPackage>Predicted information about the package to ship items in to customer
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in "Purchase order" payments
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
taxesOnShippingArray<TaxOnShipping>Taxes applied to shipping. null for old orders, [] for orders with taxes applied to subtotal only. Is calculated like: (shippingRate + handlingFee)*(taxValue/100)
totalBeforeGiftCardRedemptionnumberOrder total before gift card was redeemed. Current value is in total field.
giftCardRedemptionnumberAbsolute amount of gift card discount amount used in this order. Since this is just cart calculation, the actual gift card amount won't be changed after this request.

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn't belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredbooleantrue/false: shows whether the item requires shipping
trackQuantitybooleantrue/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlybooleantrue/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalbooleantrue/false: shows whether the item has downloadable files attached
couponAppliedbooleantrue/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item
dimensions<ProductDimensions>Product dimensions info
couponAmountnumberCoupon discount amount applied to item. Provided if discount applied to order. Is not recalculated if cart is updated later manually
discountsArray<OrderItemDiscounts>Discounts applied to cart item 'as is'. Provided if discounts are applied to cart (not including discount coupons) and are not recalculated if cart is updated later manually

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping
includeInPricebooleantrue if the tax rate is included in product prices. More details: Taxes in Ecwid

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered option value(s) as a string. For the CHOICES type, provides a string with all chosen values (comma-separated). You can use this to simply print out all selected values.
valuesArrayArraySelected option values as an array. For the CHOICES type, provides an array with the chosen values so you can iterate through them in your app.
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

OrderItemOptionFile

FieldTypeDescription
idnumberFile ID
namestringFile name
sizenumberFile size in bytes
urlstringFile URL

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress
citystringCity
countryCodestringTwo-letter country code
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name, e.g. New York
phonestringPhone number

OrderItemDiscounts

FieldTypeDescription
discountInfo<OrderItemDiscountInfo>Info about discounts applied to item
totalnumberTotal order item discount value for this discount

OrderItemDiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
orderTotalnumberMinimum order subtotal the discount applies to

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
applicationLimitstringApplication limit for discount coupons. Possible values: "UNLIMITED", "NEW_CUSTOMER_ONLY", "REPEAT_CUSTOMER_ONLY"
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

customSurchargesInfo

FieldTypeDescription
idstringSurcharge id. If not specified default value: Custom Surcharge
valuenumberSurcharge value
typestringSurcharges type: ABSOLUTE or PERCENT
totalnumberTotal value of surcharges
totalWithoutTaxnumberTotal value of surcharges without taxes
descriptionstringSurcharge description
descriptionTranslatedstringSurcharge description in the translation
taxablebooleanControls tax application for the surcharge
taxesArray<Taxes>The list of applied taxes

ShippingOptionInfo

FieldTypeDescription
shippingMethodIdstringShipping option id
shippingCarrierNamestringShipping carrier name, e.g. USPS
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Possible formats: number "5", several days estimate "4-9"
pickupInstructionstringInstruction for customer on how to receive their products
fulfillmentTypestringSupported values: PICKUP, DELIVERY, SHIPPING, default value: SHIPPING

TaxInfo

FieldTypeDescription
idnumberUnique internal ID of the tax
namestringDisplayed tax name
enabledbooleanWhether tax is enabled true / false
includeInPricebooleantrue if the tax rate is included in product prices. More details: Taxes in Ecwid
useShippingAddressbooleantrue if the tax is calculated based on shipping address, false if billing address is used
taxShippingbooleantrue is the tax applies to subtotal+shipping cost . false if the tax is applied to subtotal only
appliedByDefaultbooleantrue if the tax is applied to all products. false is the tax is only applied to thos product that have this tax enabled
defaultTaxnumberTax value, in %, when none of the destination zones match
rulesArray<TaxRule>Tax rates

TaxRule

FieldTypeDescription
zoneIdstringDestination zone ID
taxnumberTax rate for this zone in %

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
valueWithoutTaxnumberHandling fee value before applied tax
descriptionstringHandling fee description for customer
taxes<HandlingFeeTax>Taxes applied to handling fee (returns [] for orders with taxes applied to subtotal only)

HandlingFeeTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the handling fee

PredictedPackage

NameTypeDescription
heightnumberHeight of a predicted package
widthnumberWidth of a predicted package
lengthnumberLength of a predicted package
weightnumberTotal weight of a predicted package
declaredValuenumberDeclared value of a predicted package (subtotal of items in package)

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
order_totalnumberMinimum order subtotal the discount applies to
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

TaxOnShipping

FieldTypeDescription
namestringTax name
valuenumberTax value in store settings, applied to destination zone
totalnumberTax total applied to shipping

Errors

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
422No order items or incorrect items details sent
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
Language