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.
Access scopes
Requires the following access scope: create_orders
Request
A JSON object with the following fields:
📘
Parameters in bold are mandatory
Field
Type
Description
email
string
Customer email address
ipAddress
string
Customer IP
customerId
number
Unique customer internal ID (if the order is placed by a registered user)
customerTaxExempt
boolean
This field can be used to specify a customer's tax status. By default, the customer's settings from the Control Panel are used. More about this feature
discountCoupon
<DiscountCouponInfo>
Information about applied coupon
items
Array<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
discountInfo
Array<DiscountInfo>
Information about discounts applied to the order (coupons are not included). If passed ignores discounts set by store owner
giftCardCode
string
Gift card code to apply to this cart
customSurcharges
Array<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
Field
Type
Description
id
number
Order item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productId
number
Store product ID (mandatory to apply correct tax calculations for the product)
categoryId
number
ID 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
price
number
Price of ordered item in the cart
productPrice
number
Basic product price without options markups, wholesale discounts etc.
weight
number
Product weight
sku
string
Product SKU. If the chosen options match a combination, this will be a combination SKU.
quantity
number
Amount purchased
shortDescription
string
Product description truncated to 120 characters
tax
number
Tax amount applied to the item
shipping
number
Order item shipping cost
quantityInStock
number
The number of products in stock in the store
name
string
Product name
isShippingRequired
boolean
true/false: shows whether the item requires shipping. If not specified, the value is considered true
trackQuantity
boolean
true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnly
boolean
true/false: shows whether the fixed shipping rate is set for the product
imageUrl
string
Product image URL
fixedShippingRate
number
Fixed shipping rate for the product
digital
boolean
true/false: shows whether the item has downloadable files attached
couponApplied
boolean
true/false: shows whether a discount coupon is applied for this item
selectedOptions
Array<OrderItemOption>
Product options values selected by the customer
dimensions
<OrderItemDimensions>
Product dimensions info
couponAmount
number
Coupon discount amount applied to item. Provided if discount applied to order. Is not recalculated if cart is updated later manually
discounts
Array<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
Field
Type
Description
name
string
Tax name
value
number
Tax value in percent
total
number
Tax amount for the item
taxOnDiscountedSubtotal
number
Tax on item subtotal (after applying discounts)
taxOnShipping
number
Tax on item shipping
includeInPrice
boolean
true if the tax rate is included in product prices. More details: Taxes in Ecwid
OrderItemOption
Field
Type
Description
name
string
Option name
type
string
Option type. One of:
CHOICE (dropdown or radio button)
CHOICES (checkboxes)
TEXT (text input and text area)
DATE (date/time)
FILES (upload file option)
value
string
Selected/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.
valuesArray
Array
Selected 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.
files
Array<OrderItemOptionFile>
Attached files (if the option type is FILES)
selections
Array<SelectionInfo>
Details of selected product options. If sent in update order request, other fields will be regenerated based on information in this field
OrderItemOptionFile
Field
Type
Description
id
number
File ID
name
string
File name
size
number
File size in bytes
url
string
File URL
SelectionInfo
Field
Type
Description
selectionTitle
string
Selection title, as set by merchant
selectionModifier
number
Selection price modifier amount. Value is negative for negative modifiers
selectionModifierType
string
Price modifier type: "PERCENT" or "ABSOLUTE"
OrderItemDimensions
Field
Type
Description
length
number
Length of a product
width
number
Width of a product
height
number
Height of a product
PersonInfo
Field
Type
Description
name
string
Full name
companyName
string
Company name
street
string
Address
city
string
City
countryCode
string
Two-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.
countryName
string
Country name
postalCode
string
Postal/ZIP code
stateOrProvinceCode
string
State code, e.g. NY
stateOrProvinceName
string
State/province name, e.g. New York
phone
string
Phone number
OrderItemDiscounts
Field
Type
Description
discountInfo
<OrderItemDiscountInfo>
Info about discounts applied to item
total
number
Total order item discount value for this discount
OrderItemDiscountInfo
Field
Type
Description
value
number
Discount value
type
string
Discount type: ABS or PERCENT
base
string
Discount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
Discount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discount
number
Discount amount
launchDate
string
The date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDate
string
Coupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimit
number
The minimum order subtotal the coupon applies to
usesLimit
string
Number of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
applicationLimit
string
Application limit for discount coupons. Possible values: "UNLIMITED", "NEW_CUSTOMER_ONLY", "REPEAT_CUSTOMER_ONLY"
creationDate
string
Coupon creation date
orderCount
number
Number of uses
catalogLimit
<DiscountCouponCatalogLimit>
Products and categories the coupon can be applied to
DiscountCouponCatalogLimit
Field
Type
Description
products
Array<number>
The list of product IDs the coupon can be applied to
categories
Array<number>
The list of category IDs the coupon can be applied to
DiscountInfo
Field
Type
Description
value
number
Discount value
type
string
Discount type: ABS or PERCENT
base
string
Discount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM. If not specified, default value: CUSTOM
orderTotal
number
Minimum order subtotal the discount applies to. Default value: 0
description
string
Description of a discount (for discounts with base == CUSTOM)
customSurchargesDetails
Field
Type
Description
id
string
Surcharge id. If not specified default value: Custom Surcharge
value
number
Surcharge value
type
string
Surcharges type: ABSOLUTE or PERCENT. If not specified default value: ABSOLUTE
description
string
Surcharge description. Empty if not specified
taxable
boolean
Controls tax application for the surcharge. If not specified default value: false
ShippingOptionDetails
Field
Type
Description
shippingMethodId
string
Shipping option ID. Unsupported value returns error message Shipping option unavailable or Shipping option not found
shippingMethodName
string
Shipping option name. Returns Custom shipping if not specified
shippingRate
number
Total shipping rate for the order.
- Pass non-empty shippingRate to use it instead of calculating a new value (that ignores both shipping rate calculations and fixed product shipping rates)
- Pass empty shippingRate and non-empty shippingMethodId matching one of the store shipping options to make API calculate a new value for it
pickupInstruction
string
Text instructions for customer on how to receive their products at the pickup point. Requires PICKUP value in fulfillmentType field
fulfillmentType
string
Supported values: PICKUP, DELIVERY, SHIPPING. Default value: SHIPPING if not specified
PaymentOptionsDetails
Field
Type
Description
paymentId
string
Payment option id. If there are surcharges set for the payment option order total will be calculated taking into account the surcharge value.
HandlingFeeDetails
Field
Type
Description
name
string
Handling fee name. If ignored, returns Handling Fee in response
value
number
Handling fee value
description
string
Handling fee description for customer
taxes
<HandlingFeeTaxes>
Taxes applied to the handling fee
HandlingFeeTaxes
Field
Type
Description
name
string
Tax name
value
number
Tax percent value
total
number
Tax total value
Response
A JSON object with the following fields:
Field
Type
Description
subtotal
number
Order subtotal
total
number
Order total cost
email
string
Customer email address
tax
number
Tax total
ipAddress
string
Customer IP
couponDiscount
number
Discount applied to order using a coupon
paymentStatus
string
Payment status, will always be returned as INCOMPLETE
fulfillmentStatus
string
Fulfilment status, will always be returned as AWAITING_PROCESSING
volumeDiscount
number
Sum of discounts based on subtotal. Is included into the discount field
customerId
number
Unique customer internal ID (if the order is placed by a registered user)
hidden
boolean
Determines if the order is hidden (removed from the list). Applies to unfinished orders only.
membershipBasedDiscount
number
Sum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscount
number
The sum of discount based on subtotal AND customer group. Is included into the discount field
customSurcharges
Array<customSurchargesInfo>
Information about applied surcharges
discount
number
The 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
usdTotal
number
Order total in USD
createDate
date
The date/time of order placement, e.g 2014-06-06 18:57:19 +0000
createTimestamp
number
The date of order placement in UNIX Timestamp format, e.g 1427268654
discountCoupon
<DiscountCouponInfo>
Information about applied coupon
items
Array<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
availableShippingOptions
Array<ShippingOptionInfo>
All calculated shipping methods for this order (excluding methods where minimumOrderSubtotal value is above the order subtotal)
availableTaxes
Array<TaxInfo>
All calculated taxes for this order
handlingFee
<HandlingFeeInfo>
Handling fee details
predictedPackage
Array<PredictedPackage>
Predicted information about the package to ship items in to customer
additionalInfo
Map<string,string>
Additional order information if any (reserved for future use)
paymentParams
Map<string,string>
Additional payment parameters entered by customer on checkout, e.g. PO number in "Purchase order" payments
discountInfo
Array<DiscountInfo>
Information about applied discounts (coupons are not included)
taxesOnShipping
Array<TaxOnShipping>
Taxes applied to shipping. null for old orders, [] for orders with taxes applied to subtotal only. Is calculated like: (shippingRate + handlingFee)*(taxValue/100)
totalBeforeGiftCardRedemption
number
Order total before gift card was redeemed. Current value is in total field.
giftCardRedemption
number
Absolute 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
Field
Type
Description
id
number
Order item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productId
number
Store product ID
categoryId
number
ID 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
price
number
Price of ordered item in the cart
productPrice
number
Basic product price without options markups, wholesale discounts etc.
weight
number
Product weight
sku
string
Product SKU. If the chosen options match a combination, this will be a combination SKU.
quantity
number
Amount purchased
shortDescription
string
Product description truncated to 120 characters
tax
number
Tax amount applied to the item
shipping
number
Order item shipping cost
quantityInStock
number
The number of products in stock in the store
name
string
Product name
isShippingRequired
boolean
true/false: shows whether the item requires shipping
trackQuantity
boolean
true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnly
boolean
true/false: shows whether the fixed shipping rate is set for the product
imageUrl
string
Product image URL
fixedShippingRate
number
Fixed shipping rate for the product
digital
boolean
true/false: shows whether the item has downloadable files attached
couponApplied
boolean
true/false: shows whether a discount coupon is applied for this item
selectedOptions
Array<OrderItemOption>
Product options values selected by the customer
taxes
Array<OrderItemTax>
Taxes applied to this order item
dimensions
<ProductDimensions>
Product dimensions info
couponAmount
number
Coupon discount amount applied to item. Provided if discount applied to order. Is not recalculated if cart is updated later manually
discounts
Array<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
Field
Type
Description
name
string
Tax name
value
number
Tax value in percent
total
number
Tax amount for the item
taxOnDiscountedSubtotal
number
Tax on item subtotal (after applying discounts)
taxOnShipping
number
Tax on item shipping
includeInPrice
boolean
true if the tax rate is included in product prices. More details: Taxes in Ecwid
ProductDimensions
Field
Type
Description
length
number
Length of a product
width
number
Width of a product
height
number
Height of a product
OrderItemOption
Field
Type
Description
name
string
Option name
type
string
Option type. One of:
CHOICE (dropdown or radio button)
CHOICES (checkboxes)
TEXT (text input and text area)
DATE (date/time)
FILES (upload file option)
value
string
Selected/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.
valuesArray
Array
Selected 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.
files
Array<OrderItemOptionFile>
Attached files (if the option type is FILES)
OrderItemOptionFile
Field
Type
Description
id
number
File ID
name
string
File name
size
number
File size in bytes
url
string
File URL
PersonInfo
Field
Type
Description
name
string
Full name
companyName
string
Company name
street
string
Address
city
string
City
countryCode
string
Two-letter country code
countryName
string
Country name
postalCode
string
Postal/ZIP code
stateOrProvinceCode
string
State code, e.g. NY
stateOrProvinceName
string
State/province name, e.g. New York
phone
string
Phone number
OrderItemDiscounts
Field
Type
Description
discountInfo
<OrderItemDiscountInfo>
Info about discounts applied to item
total
number
Total order item discount value for this discount
OrderItemDiscountInfo
Field
Type
Description
value
number
Discount value
type
string
Discount type: ABS or PERCENT
base
string
Discount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
