Search orders
GET https://app.ecwid.com/api/v3/{storeId}/orders
Request and response example
Request:
GET /api/v3/1003/orders HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.comResponse:
{
"total": 23,
"count": 1,
"offset": 0,
"limit": 1,
"items": [
{
"id": "EBJFT",
"internalId": 492512057,
"refundedAmount": 0,
"subtotal": 500,
"subtotalWithoutTax": 500,
"total": 600,
"totalWithoutTax": 590,
"giftCardRedemption": 0,
"totalBeforeGiftCardRedemption": 600,
"giftCardDoubleSpending": false,
"email": "",
"tax": 10,
"customerTaxExempt": false,
"customerTaxIdValid": true,
"b2b_b2c": "b2c",
"reversedTaxApplied": false,
"customerRequestedInvoice": false,
"customerFiscalCode": "",
"electronicInvoicePecEmail": "",
"electronicInvoiceSdiCode": "",
"couponDiscount": 10,
"paymentStatus": "PAID",
"fulfillmentStatus": "SHIPPED",
"orderNumber": 492512057,
"vendorOrderNumber": "EBJFT",
"publicUid": "EBJFT",
"volumeDiscount": 0,
"membershipBasedDiscount": 0,
"totalAndMembershipBasedDiscount": 0,
"customSurcharges": [],
"discount": 0,
"usdTotal": 642.404477130936,
"createDate": "2024-05-01 05:26:28 +0000",
"updateDate": "2024-05-01 05:26:28 +0000",
"createTimestamp": 1714541188,
"updateTimestamp": 1714541188,
"discountCoupon": {
"id": 215189589,
"name": "Test Coupon",
"code": "DISC",
"discountType": "ABS",
"status": "ACTIVE",
"discount": 10,
"launchDate": "2024-04-30 23:00:00 +0000",
"usesLimit": "UNLIMITED",
"repeatCustomerOnly": false,
"applicationLimit": "UNLIMITED",
"creationDate": "2024-05-01 05:26:28 +0000",
"updateDate": "2024-05-01 05:26:28 +0000",
"orderCount": 0
},
"items": [
{
"id": 1741253497,
"productId": 439710255,
"price": 500,
"priceWithoutTax": 500,
"productPrice": 0,
"sku": "000001",
"quantity": 1,
"shortDescriptionTranslated": {
"ru": "",
"en": ""
},
"tax": 0,
"shipping": 0,
"quantityInStock": 0,
"name": "Pizza",
"nameTranslated": {
"ru": "",
"en": "Pizza"
},
"isShippingRequired": true,
"weight": 0,
"trackQuantity": false,
"fixedShippingRateOnly": false,
"imageUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/15695068/2870741131.jpg",
"smallThumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/15695068/2870741133.jpg",
"hdThumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/15695068/2870741134.jpg",
"fixedShippingRate": 0,
"digital": false,
"productAvailable": true,
"couponApplied": false,
"files": [
{
"productFileId": 92603033,
"maxDownloads": 0,
"remainingDownloads": 0,
"expire": "2024-05-04 05:26:28 +0000",
"name": "header.png",
"description": "",
"size": 99304,
"adminUrl": "https://app.ecwid.com/api/v3/15695068/products/439710255/files/92603033",
"customerUrl": "https://app.ecwid.com/download/15695068/d23f0e4ae9368716687f51b9d53820e2/header.png"
},
{
"productFileId": 92603034,
"maxDownloads": 0,
"remainingDownloads": 0,
"expire": "2024-05-04 05:26:28 +0000",
"name": "logo.png",
"description": "",
"size": 9487,
"adminUrl": "https://app.ecwid.com/api/v3/15695068/products/439710255/files/92603034",
"customerUrl": "https://app.ecwid.com/download/15695068/dac5865171876f936e90391236228a94/logo.png"
},
{
"productFileId": 92603035,
"maxDownloads": 0,
"remainingDownloads": 0,
"expire": "2024-05-04 05:26:28 +0000",
"name": "screen1.png",
"description": "",
"size": 56497,
"adminUrl": "https://app.ecwid.com/api/v3/15695068/products/439710255/files/92603035",
"customerUrl": "https://app.ecwid.com/download/15695068/6cb52be701b4181b733d42dfe1306e18/screen1.png"
}
],
"taxable": true,
"isCustomerSetPrice": false,
"attributes": []
}
],
"refunds": [],
"shippingOption": {
"shippingMethodId": "customShippingId",
"shippingMethodName": "Shipping",
"shippingRate": 110,
"shippingRateWithoutTax": 110,
"isPickup": false,
"fulfillmentType": "SHIPPING",
"isShippingLimit": false
},
"predictedPackage": [],
"shippingLabelAvailableForShipment": false,
"shipments": [],
"additionalInfo": {
},
"paymentParams": {
},
"extraFields": {
},
"ticket": -160802399,
"hidden": false,
"taxesOnShipping": [
{
"name": "Custom tax",
"value": 10,
"total": 10
}
],
"disableAllCustomerNotifications": false,
"externalFulfillment": false,
"utmDataSets": [],
"invoices": [],
"pricesIncludeTax": false
}
]
}Required access scopes
Your app must have the following access scopes to make this request: read_orders
Path params
All path params are required.
storeId
number
Ecwid store ID.
Query params
All query params are optional.
ids
string
List of order identifiers. Works with order ID, internal order ID, order prefixes, and suffixes.
Supports multiple values, for example: EG4H2,J77J8,SALE-G01ZG
offset
number
Offset from the beginning of the returned items list. Used when the response contains more items than limit allows to receive in one request.
Usually used to receive all items in several requests with multiple of a hundred, for example:
?offset=0 for the first request,
?offset=100, for the second request,
?offset=200, for the third request, etc.
limit
number
Limit to the number of returned items. Maximum and default value (if not specified) is 100.
keywords
string
Search term that supports: order ID, external transaction ID, billing and shipping address, customer email, shipping tracking code, item SKUs, names, selected options, and private admin notes. Any special characters must be URI-encoded.
string
Search term for customer email.
customerId
number
Search term for customer's internal ID.
productId
number/string
Search term for IDs of products in order. Supports multiple values separated by comma, for example: 10031004,86427531.
totalFrom
number
Search term for minimum order total.
totalTo
number
Search term for maximum order total.
createdFrom
number/string
Order placement datetime (lower bound). Supported formats: UNIX timestamp, date/time. Examples: 1447804800, 2023-01-15 19:27:50
createdTo
number/string
Order placement datetime (upper bound). Supported formats: UNIX timestamp, date/time. Examples: 1447804800, 2023-01-15 21:30:00
updatedFrom
number/string
Order latest update datetime (lower bound). Supported formats: UNIX timestamp, date/time. Examples: 1447804800, 2023-01-15 19:27:50
updatedTo
number/string
Order latest update date/time (upper bound). Supported formats: UNIX timestamp, date/time. Examples: 1447804800, 2023-01-15 21:30:00
pickupTimeFrom
number/string
Order pickup datetime (lower bound). Supported formats: UNIX timestamp, date/time. Examples: 1447804800, 2023-01-15 19:27:50
pickupTimeTo
number/string
Order pickup datetime (upper bound). Supported formats: UNIX timestamp, date/time. Examples: 1447804800, 2023-01-15 21:30:00
shippingMethod
string
Search term for the shipping method name selected on the checkout.
fulfillmentStatus
string
Order shipping status. Supports multiple values separated by a comma.
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.
Read more about order statuses in Help Center.
paymentMethod
string
Search term for the payment method name selected on the checkout.
paymentModule
string
Search term for the payment module selected on the checkout.
Payment module contains the name of the internal payment app (built by Ecwid dev team) or a custom one in the "paymentModule":"CUSTOM_PAYMENT_APP-client_id" format.
paymentStatus
string
Order payment status. Supports multiple values separated by a comma.
Supported values: AWAITING_PAYMENT, PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, INCOMPLETE, CUSTOM_PAYMENT_STATUS_1, CUSTOM_PAYMENT_STATUS_2, CUSTOM_PAYMENT_STATUS_3.
Read more about order statuses in Help Center.
acceptMarketing
boolean
Set true to find orders where customer has accepted email marketing.
containsPreorderItems
boolean
Set true to find orders with pre-order products (out-of-stock products available to purchase).
couponCode
string
Search term for discount coupon code applied to the order.
subscriptionId
number
Search term for ID of subscription assigned to the order.
refererId
number
Search term for ID of order referer.
responseFields
string
Specify the exact fields to receive in response JSON. If not specified, the response JSON will have all available fields for the entity.
For example: ?responseFields=total,items(id,email,total)
Example of using responseFields param:
Headers
The Authorization header is required.
Authorization
Bearer secret_ab***cd
Access token of the application.
Response JSON
A JSON object with the following fields:
total
number
Total number of found items (might be more than the number of returned items).
count
number
Total number of items returned in the response.
offset
number
Offset from the beginning of the returned items list specified in the request.
limit
number
Maximum number of returned items specified in the request. Maximum and default value: 100.
orderItems
id
string
Unique order identificator with prefix and suffix defined by the store admin. For example, order ID MYSTORE-X8UYE contains MYSTORE- prefix.
Order ID is shown to customers in any notifications and to the store owner in Ecwid admin and notifications.
subtotal
number
Cost of all products in the order (item's price x quantity) before any cost modifiers such as discounts, taxes, fees, etc. are applied.
subtotalWithoutTax
number
Order subtotal without taxes included in price (GROSS) when pricesIncludeTax is true.
total
number
Order total cost with all cost modifiers: shipping costs, taxes, fees, and discounts.
totalWithoutTax
number
Order total without taxes. Calculates as total - tax.
refundedAmount
number
Sum of all refunds applied to the order.
totalBeforeGiftCardRedemption
number
Order total before the Gift Card was applied.
string
Customer's email address.
paymentModule
string
Payment processor used to pay for the order online. Only available to online payment integrations build by Ecwid team.
paymentMethod
string
Name of the payment method customer chosen at the checkout.
tax
number
Sum of all taxes applied to products and shipping. If the order is modified after being placed, this value is not recalculated automatically.
customerTaxExempt
boolean
Defines if the customer is tax exempt. Requires valid tax ID. Read more about handling tax exempt customers in Help Center.
customerTaxId
string
Tax ID entered by the customer at the checkout.
customerTaxIdValid
boolean
Defines if customer's tax ID is valid for tax exemption.
reversedTaxApplied
boolean
Defines if order tax was reversed (set to 0). Requires valid tax ID.
b2b_b2c
string
Order type. One of:
b2b - business-to-business
b2c - business-to-consumer
customerRequestedInvoice
boolean
Defines if customer requested an invoice.
customerFiscalCode
string
Fiscale code of the customer.
electronicInvoicePecEmail
string
PEC email for order invoices.
electronicInvoiceSdiCode
string
SDI code for order invoices.
ipAddress
string
Customer's IP address detected at the checkout.
paymentStatus
string
Order payment status. Supported values: AWAITING_PAYMENT, PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, INCOMPLETE, CUSTOM_PAYMENT_STATUS_1, CUSTOM_PAYMENT_STATUS_2, CUSTOM_PAYMENT_STATUS_3.
Read more about order statuses in Help Center.
fulfillmentStatus
string
Order fulfillment 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.
Read more about order statuses in Help Center.
refererUrl
string
URL of the page when order was placed without page slugs (hash # part).
orderComments
string
Order comments, left by a customer at the checkout.
volumeDiscount
number
Sum of applied promotions based on subtotal. Included in the discount field.
membershipBasedDiscount
number
Sum of applied promotions based on customer group. Included in the discount field.
totalAndMembershipBasedDiscount
number
Sum of applied promotions based on both subtotal and customer group. Included in the discount field.
customDiscount
array of numbers
List of absolute discounts added by applications.
discount
number
Total order discount. Includes both promotions and discount coupons.
Calculated as the sum of thecouponDiscount and totalAndMembershipBasedDiscount fields.
couponDiscount
number
Discount value from applied discount coupon, e.g. 10.
Total order discount is the sum of thecouponDiscount and discount fields.
customerId
number
Unique internal ID assigned to the customer.
usdTotal
number
Order total converted from the store's currency to USD.
globalReferer
string
URL that the customer came to the store from
createDate
string
The datetime when the order was placed, for example 2014-06-06 18:57:19 +0000
updateDate
string
The datetime of the latest order update. This includes all changes made from Ecwid admin or API. For example, 2014-06-06 18:57:19 +0000
createTimestamp
number
The datetime when the order was placed in UNIX timestamp, for example 1427268654
updateTimestamp
number
The datetime of the latest order update in UNIX timestamp. This includes all changes made from Ecwid admin or API. For example, 1427268654
customerGroup
string
Name of the group the customer belongs to (if any). Read more about customer groups.
customerGroupId
number
ID of the group the customer belongs to.
shippingPerson
object shippingPerson
Name and shipping address details left by customer at the checkout.
shippingOption
object shippingOption
Details about the shipping option customer selected at the checkout.
predictedPackages
object predictedPackages
Minimum total dimensions and weight of a single shipping package that will be enough to carry all products added to the order.
shippingLabelAvailableForShipment
boolean
Defines if the store owner can buy a shipping label through Ecwid for the order.
additionalInfo
object
Internal order information for Ecwid services.
paymentParams
object
Internal payment parameters for Ecwid services.
orderExtraFields
array orderExtraFields
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.
hidden
boolean
Defines if the order is hidden from Ecwid admin. Applies to unsfinished orders only.
trackingNumber
string
Shipping tracking code.
paymentMessage
string
Error message sent by the online payment method. Only appears if a customer had issues with paying for the order online. When order becomes paid, paymentMessage is cleared
externalTransactionId
string
Transaction ID saved to the order details by the payment system. For example, PayPal transaction ID.
affiliateId
string
If a store has several storefronts, this ID is used to track from which one the order came from. Read more on setting up affiliate IDs in Help Center.
creditCardStatus
object creditCardStatus
Saves verification messages if customer paid for the order with a credit card.
privateAdminNotes
string
Private note added to the order by store owner.
pickupTime
string
Order pickup time in the store date format (UTC +0 timezone), for example: 2017-10-17 05:00:00 +0000
taxesOnShipping
array taxesOnShipping
Taxes applied to shipping 'as is'. 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)
acceptMarketing
boolean
Defines if customer has accepted email marketing at the checkout. If true or null, you can use their email for promotions.
refererId
string
Referer identifier. Can be set in storefront via JS or by creating / updating an order with REST API
disableAllCustomerNotifications
boolean
Defines if the customer should receive any email notifications:
true - no notifications are sent to the customer. If false - email notifications are sent to customer according to store mail notification settings.
This setting does not affect email notifications to the store owner.
externalFulfillment
boolean
Defines if the order is fulfilled with an external system and should not be managed through Ecwid:
true - Ecwid will hide fulfillment status change feature and ability to set tracking number within Ecwid admin.
false - store owner can manage order fulfillment within Ecwid admin (default value)
externalOrderId
string
Order ID in an external system where order is fulfilled.
Requires externalFulfillment to be true.
pricesIncludeTax
boolean
Defines if taxes are included to product prices (GROSS or NET prices):
true - the tax rate is included in product prices (GROSS).
false - the tax rate is not included in product prices (NET).
Read more about setting up taxes in Help Center.
paymentSubtype
string
Internal field for Ecwid services.
utmData
array utmData
UTM tags saved for the order. Read more about using UTM tags in orders in Help Center.
utmDataSets
array utmDataSets
Detailed information about UTM tags saved for the order. Contains more information than the utmData field.
lang
string
Defines a list of available languages or a single language for customer notifications. Must match one of the active store translations.
List of active store languages is available in the GET /profile request> languages > enabledLanguages field.
customerUserAgent
string
Details about the customer's device and platform used to place an order based on the User-Agent browser data.
externalOrderData
object externalOrderData
Details for orders created or managed externally, for example, by other Lightspeed products.
items
id
number
Order item ID unique for this order. Can be used to manage ordered items.
productId
number
Internal product ID. Can be used to find full product details with the GET /products request.
subscriptionId
number
ID of the subscription available at Ecwid admin > My Sales > Subscriptions.
categoryId
number
ID of the category this product belongs to or was added from.
Returns -1 if the product was added to the cart via the Buy Now button.
price
number
Price of product in the order with some modifiers (doesn't include discount modifiers).
Calculation: productPrice + wholesalePrices + price modifiers from selected options.
priceWithoutTax
number
Price of product in the order without taxes.
productPrice
number
Basic product price without any modifiers: options markups, discounts, taxes, fees.
costPrice
number
Purchase price of the product in the specific order used for reports and profit calculations.
weight
number
Weight of the product.
sku
string
Product SKU. If the chosen options match a variation, this will be a variation SKU.
quantity
number
Quantity of the product in the order.
shortDescription
string
Product description truncated to 120 characters.
tax
number
Total tax applied to the product.
shipping
number
Partial shipping costs specific to the product.
quantityInStock
number
Number of products in stock in the store before placing the order.
name
string
Name of the product.
isShippingRequired
boolean
Defines if the product requires shipping.
trackQuantity
boolean
Defines if low stock notifications to the store owner are enabled.
imageUrl
string
Link to the main product image.
fixedShippingRateOnly
boolean
Defines if the product has a unique fixed shipping rate.
If true, shipping costs won't calculate for the product and fixedShippingRate value will be used instead.
fixedShippingRate
number
Fixed shipping costs for the product.
Affects shipping costs only if fixedShippingRateOnly is true.
couponApplied
boolean
Defines if the product has a discount coupon applied.
selectedOptions
array selectedOptions
Product options values selected by the customer at the checkout.
combinationId
number
ID of a product variation whos options mathes with values chosen by the customer at the checkout. Read more on product variations in Help Center.
digital
boolean
Defines if the product has any downloadable files attached. Read more on digital products in Help Center.
couponAmount
number
Discount applied to the product from discount coupon.
If the order is manually updated after being placed, this field is not recalculated automatically.
taxesOnShipping
array taxesOnShipping
Taxes applied to shipping costs for the product with the calculation formula of: (shippingRate + handlingFee)*(taxValue/100)