Get order

Get all available information about an order referring to its ID. The order details include: customer email, payment/shipping method, items purchased and more.

Headers

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

Q: How can I request details of several orders at once?

When you know the exact order IDs for orders you need, you can get those order details in one request (batch request). To do that, use the Search orders method: provide the order IDS you have in the ids parameter separating them with a comma.

This way your app will save some time as you will be performing less requests to the Ecwid API and they will be much more efficient.

Q: How to get info about abandoned sales?

To get abandoned sale information, specify INCOMPLETE status for paymentStatus filter when searching for orders.

Also, check the carts endpoint methods for accessing abandoned carts

Response

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

Order

FieldTypeDescription
idstringUnique order identifier in a store. It can contain prefix and suffix defined by a store admin in Ecwid admin panel > Settings > General > Cart & checkout. Example: MYSTORE-X8UYE. It's shown to merchants and customers in UI (format can be different for old stores).
refundedAmountnumberA sum of all refunds made to order (for Chase by WePay only)
subtotalnumberOrder subtotal. Includes the sum of all products' cost in the order (item's price x quantity)
subtotalWithoutTaxnumberOrder subtotal without taxes
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
totalWithoutTaxnumberOrder total without taxes
giftCardRedemptionnumberThe amount that was deducted from the used Gift Card
totalBeforeGiftCardRedemptionnumberThe total before the Gift Card was applied
giftCardDoubleSpendingbooleanIf true, then the gift card had been already redeemed by a concurrent operation and became negative after processing this order. We advise to review orders relating to this gift card and cancel one of them (most probably this one) as necessary
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total for order. Sum of all tax in order items, unless they were modified after order was placed
customerTaxExemptbooleantrue if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidbooleantrue if customer tax ID is valid, false otherwise
reversedTaxAppliedbooleantrue if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
b2b_b2cstringOrder type: business-to-business (b2b) or business-to-consumer (b2c)
customerRequestedInvoicebooleantrue if customer requested an invoice, false otherwise
customerFiscalCodestringFiscale code of a customer
electronicInvoicePecEmailstringPEC email for invoices
electronicInvoiceSdiCodestringSDI code for invoices
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status. Supported values: Supported values: AWAITING_PAYMENT, PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, INCOMPLETE, CUSTOM_PAYMENT_STATUS_1, CUSTOM_PAYMENT_STATUS_2, CUSTOM_PAYMENT_STATUS_3.
fulfillmentStatusstringFulfilment status. Supported values: AWAITING_PROCESSING, PROCESSING, SHIPPED, DELIVERED, WILL_NOT_DELIVER, RETURNED, READY_FOR_PICKUP, OUT_FOR_DELIVERY, CUSTOM_FULFILLMENT_STATUS_1, CUSTOM_FULFILLMENT_STATUS_2, CUSTOM_FULFILLMENT_STATUS_3.
orderNumber (deprecated)numberOrder number that used to be assigned to orders. It's deprecated now and replaced with the 'id' field.
vendorOrderNumber (deprecated)stringOrder ID with prefix and suffix defined by admin. It's deprecated now and replaced with the 'id' field.
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringCustomer's order comments, specified at checkout
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)
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
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. Total order discount is a sum of all discounts applied to items (both regular discount and discount coupons) unless they were modified after order was placed
usdTotalnumberOrder total in USD
discountInfoArray <DiscountInfo>Information about applied discounts (coupons are not included)
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
updateDatedateThe date/time of the last order change, e.g 2014-06-06 18:57:19 +0000
createTimestampnumberThe date of order placement in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberThe date of the last order change in UNIX Timestamp format, e.g 1427268654
customerGroupIdnumberCustomer group ID
customerGroupstringThe name of group (membership) the customer belongs to
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray <OrderItem>Order items
refundsArray <RefundsInfo>Description of all refunds made to order (for Ecwid Payments only)
billingPerson<PersonInfo>Name and billing address of the customer. Can be omitted, if this form is disabled by merchant in Ecwid Control Panel > Settings > General > Cart > Ask for a billing address during checkout
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
predictedPackages<PredictedPackage>Predicted information about the package to ship items in to customer
shipments<Shipments>Shipment information provided to the purchased shipping label. More details: Shipping labels
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
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any. It is present and visible in order details only if order status is not paid. When order becomes paid, paymentMessage is cleared
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner
extraFields<ExtraFieldsInfo>Information about the values of the order's extra fields.
orderExtraFields<OrderExtraFieldsInfo>Additional optional information about the order's extra fields. Along with the value of the field, it contains technical information, such as id, type, etc. of the field. Total storage of extra fields cannot exceed 8Kb. See Order extra fields
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
pickupTimestringOrder pickup time in the store date format, e.g.: "2017-10-17 05:00:00 +0000"
acceptMarketingbooleantrue if customer has accepted email marketing and you can use their email for promotions (null too). If value is false, you can't use this email for promotions
disableAllCustomerNotificationsbooleantrue if no email notifications are sent to customer. If false or empty, then email notifications are sent to customer according to store mail notification settings. This field does not influence admin email notifications
externalOrderDataArray<ExternalOrderData>Data about external orders (read-only)
utmDataArray<utmData>UTM parameters tracked for the order. See more details in Help Center
invoicesArray<Invoices>Invoices created for the order (read-only)
pricesIncludeTaxbooleantrue if the tax rate is included in order price. More details: Taxes in Ecwid
utmDataSetsArray<utmDataSets>UTM parameters tracked for the order. See more details in Help Center. Advanced utmData field. Not displayed in the response if a public token is used.

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productIdnumberStore product ID
subscriptionIdnumberA subscription identifier. If a store has subscriptions, they are available at Ecwid admin panel > My Sales > Subscriptions. Learn more about Recurring subscriptions
recurringChargeSettings<RecurringChargeSettings>Information about subscription charge intervals
categoryIdnumberID of the category this product belongs to or was added from. If the product was clicked on the store front (featured products) page and added to the cart, categoryID will return 0. If the product was added to the cart via the Buy Now button on the featured products page, categoryID will return -1.
pricenumberPrice of ordered item in the cart before applying any discounts
priceWithoutTaxnumberPrice of ordered item in the cart without taxes
productPricenumberBasic product price without options markups, wholesale discounts etc.
costPricenumberPurchase price of the product in the specific order (the price at which the seller bought it from the supplier). A positive number, 0 by default. The field is not shown in the UI and can be used for reports and profit calculations
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a variation, this will be a variation SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
shortDescriptionTranslated<Translations>Available translations for product short description
taxnumberFinal tax amount applied to the item subtotal (price) with quantity and discounts applied
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
nameTranslated<Translations>Available translations for product 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
combinationIdnumberThe ID of a chosen combination
filesArray<OrderItemProductFile>Files attached to the order item
dimensions<ProductDimensions>Product dimensions info
customSurchargesArray<customSurchargesInfo>Information about applied surcharges
couponAmountnumberCoupon discount amount applied to item. Provided if discount applied to order. Is not recalculated if order is updated later manually
discountsArray<OrderItemDiscounts>Discounts applied to order item 'as is'. Provided if discounts are applied to order (not including discount coupons) and are not recalculated if order is updated later manually
taxesOnShippingArray<TaxOnShipping>Taxes applied to shipping. null for old orders, [] for orders with taxes applied to subtotal only. Are not recalculated if order is updated later manually. Is calculated like: (shippingRate + handlingFee)*(taxValue/100)
isCustomerSetPricebooleantrue if price for the ordered product was set up by a customer ("Pay What You Want" feature is enabled). false otherwise.
isPreorderbooleantrue if the product is pre-ordered because it was out of stock. Learn more about Accepting pre-orders. Otherwise the field is not returned.

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberSpecific tax amount on product subtotal (price) after applying all discounts
taxOnShippingnumberTax on item shipping
includeInPricebooleanDEPRECATED - refer to pricesIncludeTax field. true if the tax rate is included in product prices (GROSS), false otherwise (NET). More details: Taxes in Ecwid
sourceTaxRateIdnumberTax rate ID. For manual taxes the value is copied from tax ID, for all other cases the value is 0
sourceTaxRateTypestringType of tax rate, possible values are AUTO, MANUAL, CUSTOM (if tax is changed via API), LEGACY
taxTypestringType of detailed tax for USA. Possible values: STATE, COUNTY, CITY, SPECIAL_DISTRICT

OrderItemProductFile

FieldTypeDescription
productFileIdnumberInternal unique file ID
maxDownloadsnumberMax allowed number of file downloads. See E-goods article in Ecwid Help center for the details
remainingDownloadsnumberRemaining number of download attempts
expirestringDate/time of the customer download link expiration
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringLink to the file. Be careful: the link contains the API access token. Make sure you do not display the link as is in your application and not give it to a customer.
customerUrlstringFile download link that is sent to the customer when the order is paid

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown, radio button or size)
  • 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"

RecurringChargeSettings

FieldTypeDescription
recurringIntervalstringSubscription charge interval. Supported values: DAY, WEEK, MONTH, YEAR
recurringIntervalCountnumberCharge interval count (e.g. 3 - once per 3 months)
subscriptionPriceWithSignUpFeenumberThe cost of the product for the first subscription order.
signUpFeenumberThe size of the markup that is imposed on the first order.

Translations

FieldTypeDescription
<ISO_LANG_CODE>stringTranslations for each available language. If no other translations are provided, the default language translations is returned. See available languages in store language settings

ProductDimensions

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

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by '\n'
citystringCity
countryCodestringTwo-letter country code
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name, e.g. New York
phonestringPhone number

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

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

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
shippingMethodIdstringShipping method ID
shippingMethodNamestringShipping option name
shippingRatenumberRate
shippingRateWithoutTaxnumberRate without tax
estimatedTransitTimestringDelivery time estimation. (Currently is equal to the description field of the GET shipping option request)
isPickupbooleantrue for pickup methods, false otherwise
pickupInstructionstringInstruction for customer on how to receive their products
fulfillmentTypestringContains one of the values: shipping, pickup, delivery

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
valueWithoutTaxnumberHandling fee value without taxes
descriptionstringHandling fee description for customer
taxes<HandlingFeeTaxes>Taxes applied to the handling fee

HandlingFeeTaxes

FieldTypeDescription
namestringTax name
valuenumberTax percent value
totalnumberTax total value

PredictedPackage

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

Shipments

FieldTypeDescription
idstringID of the purchased shipping label
createddateThe date/time of shipping label purchase, e.g 2020-04-23 19:13:43 +0000
shipTo<PersonInfo>Name and address of the person entered in shipping information
shipFrom<ShippingOrigin>Shipping origin address. If matches company address, company address is returned
parcel<PackageInfo>Information about the selected package to ship items to customer
shippingService<ShippingService>Selected shipping service
tracking<Tracking>Tracking details provided by shipping service
shippingLabel<ShippingLabel>Shipping label details

ShippingOrigin

Settings → Shipping & Pickup → Origin address

FieldTypeDescription
companyNamestringThe company name displayed on the invoice
streetstringCompany address. 1 or 2 lines separated by a new line character
citystringCompany city
countryCodestringA two-letter ISO code of the country
postalCodestringPostal code or ZIP code
stateOrProvinceCodestringState code (e.g. NY) or a region name
phonestringCompany phone number

PackageInfo

FieldTypeDescription
weightnumberTotal weight of a package
weightUnitstringContains one of the values: CARAT, GRAM, OUNCE, POUND, KILOGRAM
widthnumberWidth of a package
heightnumberHeight of a package
lengthnumberLength of a package
dimensionUnitstringContains one of the values: MM, CM, IN, YD

ShippingService

FieldTypeDescription
carrierstringCarrier used for shipping the order. Contains one of the values: USPS, UPS, FEDEX, CANADA_POST, AUSTRALIA_POST
carrierNamestringName of shipping option in store settings
carrierServiceNamestringSpecific carrier method name
carrierServiceCodestringSpecific carrier method code

Tracking

FieldTypeDescription
tracking_numberstringTracking number provided by shipping service
tracking_urlstringLink for tracking delivery status information
estimatedDaysnumberEstimated delivery time in days

ShippingLabel

FieldTypeDescription
label_urlstringURL to download shipping label

DiscountInfo

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
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

ExtraFieldsInfo

FieldTypeDescription
ecwid_order_delivery_time_interval_enddateEnd of the delivery date interval.
ecwid_order_delivery_time_display_formatstringFormat of the delivery date chosen:DATE or DATETIME.
ecwid_order_delivery_time_interval_startdateStart of the delivery date interval.

OrderExtraFieldsInfo

FieldTypeDescription
idstringYour custom name saved for the order extra field
valuestringExtra field value. Length cannot exceed 255 characters
customerInputTypestringOne of: "","TEXT", "SELECT", "DATETIME"
titlestringExtra field title. Displayed for customer at checkout if field is visible
orderDetailsDisplaySectionstringOne of: shipping_info , billing_info, customer_info, order_comments. Empty string for hidden fields.
orderBystringExtra field position. Use it to sort fields within the same orderDetailsDisplaySection.

RefundsInfo

FieldTypeDescription
datedateThe date/time of a refund, e.g 2014-06-06 18:57:19 +0000
sourcestringWhat action triggered refund. Possible values: "CP" - changed my merchant in Ecwid CP, "API" - changed by another app, "External" - refund made from payment processor website
reasonstringA text reason for a refund. 256 characters max
amountnumberAmount of this specific refund (not total amount refunded for order. See redundedAmount field)

ExternalOrderData

FieldTypeDescription
externalFulfillmentbooleanSet true if order is fulfilled in an external system; Ecwid will hide fulfillment status change feature and ability to set tracking number within Ecwid Control Panel in order details. Set false to manage order fulfillment within Ecwid Control Panel
externalOrderIdstringCorresponding order number in an external system where order is fulfilled. Use together with the externalFulfillment field
refererIdstringReferer identifier. Can be set in storefront via custom JS code or by creating / updating an order with REST API
refererChannelstringReferer channel identifier. Can be set in storefront via JS or by creating / updating an order with REST API

utmData

FieldTypeDescription
sourcestringTraffic source - indicated where customers come from
campaignstringIndicates a specific advertising campaign
mediumstringType of traffic - indicates the method for bringing customers

utmDataSets

FieldTypeDescription
timestampnumberThe time of saving dataset into the local storage
sourcestringTraffic source - indicated where customers come from
mediumstringType of traffic - indicates the method for bringing customers
campaignstringIndicates a specific advertising campaign

Invoices

FieldTypeDescription
internalIdnumberInternal ID of the invoice
idstringPublic invoice ID showed in the invoice
createdstringDate and time of invoice creation in UTC
linkstringDownload link for invoice in PDF format
typestringInvoice type. Supported values "SALE" (regular), "FULL_CANCEL" (refund)

TaxOnShipping

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

IsCustomerSetPrice

FieldTypeDescription
selectedPrice → value<SelectedPriceValue>Value of the price tier selected by a customer.

Errors

Error response example:

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

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

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The store is suspended
403Access token doesn't have read_orders scope
404The order is not found
405Method not allowed. Can occur when using POST instead of PUT HTTP request method
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
Language
Authentication
Query