# Search orders
`GET` `https://app.ecwid.com/api/v3/{storeId}/orders`
Request and response example
Request:
```http
GET /api/v3/1003/orders HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.com
```
Response:
```json
{
"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.
| Param | Type | Description |
| ------- | ------ | --------------- |
| storeId | number | Ecwid store ID. |
### Query params
All query params are optional.
| Name | Type | Description |
|---|
| 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. |
| email | 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:
{% tabs %}
{% tab title="Request" %}
```
curl --location 'https://app.ecwid.com/api/v3/1003/orders?responseFields=total,items(id,email,total)' \
--header 'Authorization: Bearer secret_ab***cd'
```
{% endtab %}
{% tab title="Response" %}
```json
{
"total": 3,
"items": [
{
"id": "K8XTQ",
"email": "artem.kudryashov@lightspeedhq.com",
"total": 10
},
{
"id": "1HOTQ",
"email": "artem.kudryashov@lightspeedhq.com",
"total": 101
},
{
"id": "CYQLB",
"email": "artem.kudryashov@lightspeedhq.com",
"total": 109.1
}
]
}
```
{% endtab %}
{% endtabs %}
### Headers
The **Authorization** header is required.
| Header | Format | Description |
|---|
| Authorization | Bearer secret_ab***cd | Access token of the application. |
### Response JSON
A JSON object with the following fields:
| Field | Type | Description |
| ------ | ------------------------------------------ | -------------------------------------------------------------------------------------------- |
| 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`. |
| items | array of objects [orderItems](#orderitems) | Detailed information about returned orders. |
#### orderItems
| Field | Type | Description |
| --------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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. |
| giftCardRedemption | number | Amount deducted from the [Gift Card](https://support.ecwid.com/hc/en-us/articles/360002011419) balance and applied to order total. |
| totalBeforeGiftCardRedemption | number | Order total before the Gift Card was applied. |
| email | 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.
|
| discountInfo | array [discounts](#discounts) | Detailed information about applied **promotions**. |
| discountCoupon | object [discountCoupon](#discountcoupon) | Detailed information about applied **discount coupons**. |
| customerId | number | Unique internal ID assigned to the customer. |
| customSurcharges | array of objects [customSurcharges](#customsurcharges) | Information about surcharges applied to the order. |
| 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. |
| items | array [items](#items) | Detailed information about products in the order. |
| refunds | array [refunds](#refunds) | Details about refunds made to order. |
| shippingPerson | object [shippingPerson](#shippingperson) | Name and shipping address details left by customer at the checkout. |
| billingPerson | object [billingPerson](#billingperson) | Name and billing address details left by customer at the checkout. |
| shippingOption | object [shippingOption](#shippingoption) | Details about the shipping option customer selected at the checkout. |
| handlingFee | object [handlingFee](#handlingfee) | Details about fees applied to order. |
| predictedPackages | object [predictedPackages](#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. |
| shipments | array [shipments](#shipments) | Detailed information about purchased shipping label. |
| additionalInfo | object | Internal order information for Ecwid services. |
| paymentParams | object | Internal payment parameters for Ecwid services. |
| extraFields | object [extraFields](#extrafields) | Names and values of custom checkout fields applied to the order. |
| orderExtraFields | array [orderExtraFields](#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](#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](#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.
|
| invoices | array [invoices](#invoices) | Tax invoices generated for the order.
Read-only
|
| 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](#utmdata) | UTM tags saved for the order.
Read more about using UTM tags in orders in Help Center.
|
| utmDataSets | array [utmDataSets](#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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) browser data. |
| externalOrderData | object [#externalorderdata](#externalorderdata "mention") | Details for orders created or managed externally, for example, by other Lightspeed products. |
#### items
| Field | Type | Description |
|---|
| 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. |
| recurringChargeSettings | object recurringChargeSettings | Details about subscription charge intervals. |
| 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. |
| shortDescriptionTranslated | object translations | Available translations for product short description. |
| 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. |
| nameTranslated | object translations | Available translations for the product name. |
| 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. |
| taxes | array taxes | Detailed information about taxes applied to the product in this order. |
| 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. |
| files | array of objects files | Details about downloadable files attached to the product. |
| dimensions | object dimensions | Details about product dimensions used for shipping costs calculations. |
| 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.
|
| discounts | array discounts | Promotions applied to the specific product in the order. |
| taxesOnShipping | array taxesOnShipping | Taxes applied to shipping costs for the product with the calculation formula of: (shippingRate + handlingFee)*(taxValue/100)
If the order is manually updated after being placed, this field is not recalculated automatically.
|
| taxAlreadyDeductedFromPrice | boolean | Indicates whether the taxes have been already deducted from the price. |
| isCustomerSetPrice | boolean | If true, customer set a custom product price using the "Pay What You Want" feature.
In this case, both the product price and selectedPrice -> value fields contain the price set by a customer.
If false, customer didn't choose the custom price. Therefore, the selectedPrice -> value field will be absent and the price field contains default product price set by the store owner. |
| selectedPrice | object selectedPrice > value | If isCustomerSetPrice is true, this field contains the "Pay What You Want" price set by a customer at the checkout. Example with the PWYW price set to 100:
"selectedPrice": { "value": 100 } |
| isPreorder | boolean | Defines if the product was pre-ordered in this order.
Read more about accepting pre-orders in Help Center. |
| attributes | array of objects attributes | Details about product attributes.
Read more on product attributes in Help Center. |
#### attributes
| Field | Type | Description |
| ----- | ------ | ------------------------------ |
| name | string | Name of the product attribute. |
| value | string | Attribute value. |
#### taxes
| Field | Type | Description |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Name of the tax visible to customers at the checkout and in order invoices. |
| value | number | Tax value in percent. |
| total | number | Tax amount applied to the product. |
| taxOnDiscountedSubtotal | number | Tax applied to product price (`price`) after all discounts. |
| taxOnShipping | number | Tax applied to the shipping costs of the product. |
| sourceTaxRateId | number | Tax rate ID. For manual taxes the value is copied from tax ID, for all other cases the value is `0`. |
| sourceTaxRateType | string | Type of tax rate.
One of AUTO, MANUAL, CUSTOM (if tax is changed via API), LEGACY.
|
| taxType | string | Type of detailed tax for USA.
One of: STATE, COUNTY, CITY, SPECIAL\_DISTRICT
|
| taxClassCode | string | Tax classification code applied to product.
See: Tax classes by country
|
| taxClassName | string | Name of the tax classification code applied to product. Available only in English.
See: Tax classes by country
|
#### files
| Field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| productFileId | number | Internal unique file ID. |
| maxDownloads | number | Maximum number of allowed file downloads.
Read more on digital products in Help Center.
|
| remainingDownloads | number | Remaining number of download attempts for the file. |
| expire | string | Date/time of the customer download link expiration. |
| name | string | File name visible to the customer. |
| description | string | File description visible to the customer. |
| size | number | File size in bytes (64-bit integer). |
| adminUrl | string | Link to the file download for the store owner.
Keep caution: the link contains the API access token. Never share it and do not display the link in publically available code.
|
| customerUrl | string | File download link sent to the customer after the order was paid. |
#### selectedOptions
| Field | Type | Description |
| ----------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Name of the product option. |
| type | string | Type of the product option that defines its functionality.
One of:
CHOICE - Dropdown, radio button, or size. Allows selecting only one value from the list.
CHOICES - Checkbox. Allows selecting multiple values.
TEXT - Text input or area.
DATE - Datetime selector.
FILES - Upload file option.
|
| value | string | Selected/entered value for the option as string.
For CHOICES type, provides a string with all selected values separated by a comma.
|
| valuesArray | array | Selected/entered value for the option as array.
For the CHOICES type, provides an array with all selected values.
|
| files | array of objects | Detailed information about files attached to the selected option.
Available only if the option type is FILES.
|
| selections | array of objects | Details of selected product options.
If sent in "Update order" request, other fields will be recalculated based on information from selections.
|
| hexCodes | array of strings | List of HEX codes.
Defines what color must be displayed when user changes color in the SWATCHES option, for example: \["#fff000"].
Requires useImageAsSwatchSelector to be true.
|
| changedTime | number | UNIX timestamp of the latest change in the product option. |
#### filesAttached
| Field | Type | Description |
| ----- | ------ | ----------------------------------------------------------------- |
| id | number | ID of the file uploaded through `FILES` type option. |
| name | string | Name of the file uploaded through `FILES` type option. |
| size | number | Size (in bytes) of the file uploaded through `FILES` type option. |
| url | string | Download link of the file uploaded through `FILES` type option. |
#### selections
| Field | Type | Description |
| --------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| selectionTitle | string | Name of the selected option value. |
| selectionModifier | number | Price modifier of the selected option value.
Value can be negative, for example, -10 if it decreases the product price.
|
| selectionModifierType | string | Price modifier type.
One of:
PERCENT - Price modifier applies as a percent from the product price.
ABSOLUTE - Price modifier applies as a flat value.
|
#### recurringChargeSettings
| Field | Type | Description |
|---|
| recurringInterval | string | Subscription charge interval.
One of: day, week, month, year.
|
| recurringIntervalCount | number | Charge interval count that depends on the recurringInterval. For example 3 - once per 3 months, if recurringInterval is month. |
| subscriptionPriceWithSignUpFee | number | Total product cost including the first subscription payment. |
| signUpFee | number | Fees imposed on the first payment. |
#### dimensions
| Field | Type | Description |
| ------ | ------ | ------------------- |
| length | number | Length of a product |
| width | number | Width of a product |
| height | number | Height of a product |
#### shippingPerson
| Field | Type | Description |
| ------------------- | ------ | ----------------------------------------------------- |
| name | string | Full name of the customer. |
| companyName | string | Customer's company name. |
| street | string | Address line 1 and address line 2, separated by `\n`. |
| city | string | City. |
| countryCode | string | Two-letter country code. |
| countryName | string | Country name. |
| postalCode | string | Postal/ZIP code. |
| stateOrProvinceCode | string | State/province code, for example, `NY`. |
| stateOrProvinceName | string | State/province name. |
| phone | string | Customer's phone number. |
#### billingPerson
| Field | Type | Description |
| ------------------- | ------ | ----------------------------------------------------- |
| name | string | Full name of the customer. |
| companyName | string | Customer's company name. |
| street | string | Address line 1 and address line 2, separated by `\n`. |
| city | string | City. |
| countryCode | string | Two-letter country code. |
| countryName | string | Country name. |
| postalCode | string | Postal/ZIP code. |
| stateOrProvinceCode | string | State/province code, for example, `NY`. |
| stateOrProvinceName | string | State/province name. |
| phone | string | Customer's phone number. |
#### customSurcharges
| Field | Type | Description |
| --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | string | Surcharge ID.
If not specified default value: Custom Surcharge
|
| value | number | Surcharge value. |
| type | string | Surcharges type.
One of:
"PERCENT" - Surcharge applies as a percent from the product price.
"ABSOLUTE" - Surcharge applies as a flat value.
|
| total | number | Total value of the surcharge. |
| totalWithoutTax | number | Total value of the surcharge without taxes. |
| description | string | Surcharge description defined by the store owner. |
| descriptionTranslated | string | Available translations for the surcharge description. |
| taxable | boolean | Defines if taxes apply to the surcharge. |
| taxes | array [taxes](#taxes) | Details about taxes applied to the surcharge. |
#### discounts
| Field | Type | Description |
| ------------ | ---------------------------------------------- | ---------------------------------------------------- |
| discountInfo | array of objects [discountInfo](#discountinfo) | Details about **promotions** applied to the product. |
| total | number | Sum of **promotions** applied to the order. |
#### discountCoupon
| Field | Type | Description |
| ---------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | number | Internal discount coupon ID. |
| name | string | Name of the discount coupon visible in Ecwid admin. |
| code | string | Discount coupon code. |
| discountType | string | Discount type.
One of:
ABS
PERCENT
SHIPPING
ABS\_AND\_SHIPPING
PERCENT\_AND\_SHIPPING
|
| status | string | Discount coupon state.
One of:
ACTIVE
PAUSED
EXPIRED
USEDUP
|
| discount | number | Discount value applied to the order total. |
| launchDate | string | The date of coupon launch, for example, `2014-06-06 08:00:00 +0000`. |
| expirationDate | string | Coupon expiration date, for example, `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.
One of:
UNLIMITED
NEW\_CUSTOMER\_ONLY
REPEAT\_CUSTOMER\_ONLY
|
| creationDate | string | Discount coupon creation date. |
| updateDate | string | Date of the last discount coupon update. |
| orderCount | number | Amount of orders where the discount coupon was used previously. |
| catalogLimit | object [catalogLimit](#cataloglimit) | Products and categories the coupon can be applied to |
#### catalogLimit
| Field | Type | Description |
| ---------- | ---------------- | -------------------------------------------------- |
| products | array of numbers | List of product IDs the coupon can be applied to. |
| categories | array of numbers | List of category IDs the coupon can be applied to. |
#### shippingOption
| Field | Type | Description |
| ----------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| shippingCarrierName | string | If an order is fulfilled with a native shipping carrier integration or a shipping app, this field holds carrier's name. |
| shippingMethodName | string | Name of the shipping option visible at the checkout. |
| shippingMethodId | string | Internal shipping method ID. |
| shippingRate | number | Shipping rate for the order. |
| shippingRateWithoutTax | number | Shipping rate without taxes. |
| discountedShippingRate | number | Shipping rate with applied shipping discounts.
Read-only
|
| estimatedTransitTime | number/string | Delivery time estimation.
Depending on the store settings it can be a number, for example, 5 or a string – 4-9 days.
The string value is equal to the description field in the Get shipping options request.
|
| isPickup | boolean | Defines if this is a store pickup method. |
| pickupInstruction | string | Instructions for customer on how to pickup the order. |
| fulfillmentType | string | Shipping type.
One of:
shipping
pickup
deliver
|
| timeSlotLengthInMinutes | number | Length of the delivery time slot in minutes. |
| discount | object [shippingOptionDiscount](#shippingoptiondiscount) | DIscount applied to the shipping method. |
#### shippingOptionDiscount
| Field | Type | Description |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------- |
| id | string | Internal discount ID |
| value | number | Discount value. |
| type | string | Discount type: `PERCENT` or `ABSOLUTE`. |
| base | string | Base from which the discount is calculated. For example, `SHIPPING`. |
| orderTotal | number | Order total cost before the discount is applied. |
| description | string | Discount name/description. |
| appliesToItems | array of numbers | Internal IDs of items discount is applied to. |
| appliesToOrderItems | array of numbers | Numbered IDs of items in the order (`0`, `1`, `2`, etc.) discount is applied to. |
| triggeredByOrderItems | array of numbers | Internal IDs of items that triggered the discount. |
| appliesToShippingMethodId | string | Id of the shipping method discount applies to. For example, `"6589-1709547151586"`. |
#### handlingFee
| Field | Type | Description |
| ----------- | ------ | -------------------------------------------------------------- |
| name | string | Handling fee name set by store admin, for example, `Wrapping`. |
| value | number | Handling fee flat value. |
| description | string | Handling fee's description for customers. |
#### predictedPackages
| Name | Type | Description |
| ------------- | ------ | --------------------------------------------------------------------- |
| height | number | Height of a predicted package. |
| width | number | Width of a predicted package. |
| length | number | Length of a predicted package. |
| weight | number | Total weight of a predicted package. |
| declaredValue | number | Declared value of a predicted package (subtotal of items in package). |
#### shipments
| Field | Type | Description |
| --------------- | ------------------------------------------ | ---------------------------------------------------------------------------------- |
| id | string | ID of the purchased shipping label. |
| created | date | The date/time of shipping label purchase, for example, `2020-04-23 19:13:43 +0000` |
| shipTo | object [shippingPerson](#shippingperson) | Name and address of the person entered in shipping information. |
| shipFrom | object [shipFrom](#shipfrom) | Shipping origin address. If matches company address, company address is returned. |
| parcel | object [parcel](#parcel) | Information about the selected package to ship items to customer. |
| shippingService | object [shippingService](#shippingservice) | Selected shipping service. |
| tracking | object [tracking](#tracking) | Tracking details provided by shipping service. |
| shippingLabel | object [shippingLabel](#shippinglabel) | Shipping label details. |
#### shipFrom
| Field | Type | Description |
| ------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| companyName | string | Store owner's company name. |
| email | string | Store owner's email. |
| street | string | Store's address in 1 or 2 lines format. If two address lines provided, they are separated by `\n`. |
| city | string | City where the store is located. |
| countryCode | string | Two-letter country code. |
| countryName | string | Country where the store is located. |
| postalCode | string | Postal/ZIP code for the store's location. |
| stateOrProvinceCode | string | State/province code, for example, `NY`. |
| stateOrProvinceName | string | State/province name. |
| phone | string | Store's phone number. |
#### parcel
| Field | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| weight | number | Total weight of the labeled package. |
| weightUnit | string | Weight unit of the package.
One of:
CARAT
GRAM
OUNCE
POUND
KILOGRAM
|
| width | number | Width of the labeled package. |
| height | number | Height of the labeled package. |
| length | number | Length of the labeled package. |
| dimensionUnit | string | Dimension unit of the package.
One of:
MM
CM
IN
YD
|
#### shippingService
| Field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| carrier | string | Carrier used for shipping the order. Available only for integrations build by Ecwid team.
One of:
USPS
UPS
FEDEX
CANADA\_POST
AUSTRALIA\_POST
|
| carrierName | string | Name of shipping option in store settings. |
| carrierServiceName | string | Specific carrier's name visible at the checkout. |
| carrierServiceCode | string | Internal carrier code. |
#### tracking
| Field | Type | Description |
| ---------------- | ------ | ------------------------------------------------- |
| tracking\_number | string | Tracking number provided by the shipping service. |
| tracking\_url | string | Link to the delivery tracking page. |
| estimatedDays | number | Estimated delivery time in days. |
#### shippingLabel
| Field | Type | Description |
| ---------- | ------ | --------------------------------- |
| label\_url | string | Link for download shipping label. |
#### discountInfo
| Field | Type | Description |
|---|
| id | number | Internal discount ID. |
| value | number | Discount value. |
| type | string | Discount type.
One of: |
| base | string | Discount base.
One of: SUBTOTAL - Discount is based on order subtotal.ITEM - Discount is only applied to certain products in the order.SHIPPING - Discount is only applied to order shipping costs.ON_MEMBERSHIP - Discount is only applied if customer belongs to a certain customer group.ON_TOTAL_AND_MEMBERSHIP - Discount is applied to CUSTOM - Discount is created by an app with a custom logic.
|
| orderTotal | number | Minimum order subtotal the discount applies to. |
| membershipId | number | Customer group ID to which the discount is limited. |
| description | string | Description of a discount visible at the checkout. Available only for discounts with CUSTOM base. |
| appliesToItems | array of numbers | List of product IDs to which the discount can be applied. |
| appliesToOrderItems | array of objects | List of internal order item IDs, which defines a list of products the discount is applied in this specific order. |
#### creditCardStatus
| Field | Type | Description |
| ---------- | ------ | --------------------------------------------------------------- |
| avsMessage | string | Address verification status returned by the payment system. |
| cvvMessage | string | Credit card verification status returned by the payment system. |
#### extraFields
| Field | Type | Description |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| ecwid\_order\_delivery\_time\_interval\_start | string | Start of the delivery date/datetime interval. |
| ecwid\_order\_delivery\_time\_interval\_end | string | End of the delivery date/datetime interval. |
| ecwid\_order\_delivery\_time\_display\_format | string | Format of the delivery date chosen.
One of:
DATE
DATETIME
|
#### orderExtraFields
| Field | Type | Description |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | string | Internal ID defined for the checkout extra field. |
| value | string | Extra field value. Length cannot exceed 255 characters. |
| customerInputType | string | One of: `""`,`"TEXT"`, `"SELECT"`, `"DATETIME"` |
| title | string | Extra field title visible at the checkout. |
| orderDetailsDisplaySection | string | Defines a place where the field is visible to the store admin on the order details page.
One of:
shipping\_info
billing\_info
customer\_info
order\_comments
Empty if the field is hidden.
|
| orderBy | string | Extra field position. Use it to sort fields within the same `orderDetailsDisplaySection` |
#### refunds
| Field | Type | Description |
| ------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| date | string | The datetime of a refund, for example, `2014-06-06 18:57:19 +0000` |
| source | string | What action triggered refund.
One of:
CP - changed by the store owner in Ecwid admin
API - changed by an app through API
External - refund made from payment processor website
|
| reason | string | A text reason for a refund. 256 characters max. |
| amount | number | Amount of this specific refund (not total amount refunded for order. see `redundedAmount` field) |
#### utmData
| Field | Type | Description |
| -------- | ------ | ----------------------------------------------------------- |
| source | string | Traffic source that indicates where the customer come from. |
| campaign | string | Saves the name of the advertising campaign if there is one. |
| medium | string | Type of traffic that indicates customers reach the website. |
#### utmDataSets
| Field | Type | Description |
| --------- | ------ | ----------------------------------------------------------- |
| timestamp | string | Datetime of saving UTM data into the local browser storage. |
| source | string | Traffic source that indicates where the customer come from. |
| campaign | string | Saves the name of the advertising campaign if there is one. |
| medium | string | Type of traffic that indicates customers reach the website. |
#### invoices
| Field | Type | Description |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| internalId | number | Internal ID of the order invoice. |
| id | string | Public ID showed in the invoice. |
| created | string | Datetime of invoice creation in UTC +0. |
| link | string | Download link for the invoice in PDF format. |
| type | string | Invoice type.
One of:A
SALE - regular invoice
FULL\_CANCEL - full refund invoice
|
#### taxesOnShipping
| Field | Type | Description |
| ----- | ------ | ------------------------------------------- |
| name | string | Name of the tax applied to shipping costs. |
| value | number | Value of the tax applied to shipping costs. |
| total | number | Total of taxes applied to shipping costs. |
#### externalOrderData
| Field | Type | Description |
| ---------------------- | ------- | --------------------------------------------------------------- |
| externalOrderId | string | Order ID from the external platform. |
| externalFulfillment | boolean | Defines if the order uses external fulfillment. |
| refererChannel | string | Channel where the order is referred from. |
| refererId | string | Unique referrer ID for the order. |
| platformSpecificFields | string | Stringified map with external fields in the "key:value" format. |
#### translations
Object with text field translations in the `"lang": "text"` format, where the `"lang"` is an ISO 639-1 language code. For example:
```
{
"en": "Sample text",
"nl": "Voorbeeldtekst"
}
```
Translations are available for all active store languages. Only the default language translations are returned if no other translations are provided for the field. Find active store languages with `GET` `/profile` request > `languages` > `enabledLanguages`.