Ecwid

Ecwid REST API v3 integration for managing e-commerce store data including products, orders, customers, categories, discount coupons, promotions, abandoned carts, and store profile.

Official docs: https://docs.ecwid.com/api-reference
Publisher: https://github.com/droneitgroup

---

Connection Setup

Set up a Direct API (HTTP) connection with the following settings:

Setting	Value
Service name	Ecwid
Base URL

https://app.ecwid.com/api/v3/{storeId} (replace {storeId} with your actual store ID) |
| Auth type | Bearer token |
| Token | Your store's secret API token (format: secret_xxxxx) |
| HTTP methods | GET for read-only access. Add POST, PUT, DELETE for write operations. |

Finding your Store ID and API token

1. 1. Log in to your Ecwid admin panel
2. Go to Settings → API
3. Your Store ID is displayed at the top
4. Your Secret API token starts with secret_ — use this as the Bearer token

⚠️ Security best practices

• - Use the minimum scopes needed. If you only need to read data, create a token with read-only scopes (e.g. read_store_profile, read_catalog, read_orders, read_customers, read_discount_coupons) and set HTTP methods to GET only.
• Never use a full admin token unless you specifically need write access.
• Test with a sandbox/test store first before connecting a production store.
• Rotate tokens if you suspect they've been exposed.
• For more on Ecwid API permissions, see: https://docs.ecwid.com/api-reference/rest-api/authentication

---

Common Patterns

Pagination

All list endpoints return the same pagination envelope:

CODEBLOCK0

Use offset and limit query parameters to paginate. Maximum and default limit is 100.

Example: ?offset=0 → ?offset=100 → ?offset=200 ...

Response field filtering

All endpoints support the responseFields query parameter to limit which fields are returned:

CODEBLOCK1

This reduces response size and speeds up requests.

Date formats

Date parameters accept both:

• - UNIX timestamps: INLINECODE21
• Datetime strings: INLINECODE22

Authentication

All requests require the Authorization header:

Authorization: Bearer secret_xxxxx

---

Products

Scope required: INLINECODE24

Search/list products

CODEBLOCK3

Query parameters

Name	Type	Description
INLINECODE25	string	Search term. Searches name, description, SKU, options, category name, gallery image descriptions, attribute values. Add * at end to disable exact match.
INLINECODE27

number | Internal product IDs (comma-separated). If set, other search params are ignored. | | sku | string | Exact product or variation SKU match. If set, other params ignored except productId. | | category | string | Category ID to filter products by. | | categories | string | Comma-separated category IDs, e.g. 0,123456,138470508. | | includeProductsFromSubcategories | boolean | Set true to include products from subcategories. | | priceFrom | number | Minimum product price. | | priceTo | number | Maximum product price. | | createdFrom | number/string | Product creation date lower bound. | | createdTo | number/string | Product creation date upper bound. | | updatedFrom | number/string | Product update date lower bound. | | updatedTo | number/string | Product update date upper bound. | | enabled | boolean | true for enabled only, false for disabled only. | | inStock | boolean | true for in-stock only, false for out-of-stock only. | | sortBy | string | One of: RELEVANCE (default), DEFINED_BY_STORE_OWNER, ADDED_TIME_DESC, ADDED_TIME_ASC, NAME_ASC, NAME_DESC, PRICE_ASC, PRICE_DESC, UPDATED_TIME_ASC, UPDATED_TIME_DESC. | | offset | number | Pagination offset. | | limit | number | Max items to return (max/default: 100). | | responseFields | string | Limit response fields. Example: items(id,name,price,sku) |

Key response fields (items)

Field	Type	Description
INLINECODE62	number	Internal product ID.
INLINECODE63

string | Product SKU. | | name | string | Product name. | | price | number | Base product price. | | defaultDisplayedPrice | number | Price shown on storefront (includes taxes). | | compareToPrice | number | Pre-sale / "compare to" price. | | quantity | number | Stock quantity (absent if unlimited is true). | | unlimited | boolean | Whether product has unlimited stock. | | inStock | boolean | Whether in stock. | | enabled | boolean | Whether visible on storefront. | | weight | number | Product weight. | | url | string | Storefront product page URL. | | created | string | Creation datetime. | | updated | string | Last update datetime. | | createTimestamp | number | Creation UNIX timestamp. | | updateTimestamp | number | Last update UNIX timestamp. | | description | string | Product description (HTML). | | categoryIds | array | IDs of assigned categories. | | defaultCategoryId | number | Default category ID. | | imageUrl | string | Main image URL (1200px). | | thumbnailUrl | string | Thumbnail URL (400px). | | originalImageUrl | string | Full-size image URL. | | options | array | Product options (size, color, etc.). | | combinations | array | Product variations. | | attributes | array | Product attributes and values. | | isGiftCard | boolean | Whether this is a gift card. |

Example

CODEBLOCK4

Get single product

CODEBLOCK5

Returns the full product object directly (not wrapped in pagination envelope). The productId is a number.

---

Orders

Scope required: INLINECODE90

Search/list orders

CODEBLOCK6

Query parameters

Name	Type	Description
INLINECODE91	string	Comma-separated order IDs, internal IDs, prefixes, and suffixes. Example: INLINECODE92
INLINECODE93

string | Search order ID, transaction ID, addresses, email, tracking code, item SKUs/names, admin notes. | | email | string | Customer email. | | customerId | number | Customer's internal ID. | | productId | number/string | Product IDs in order (comma-separated). | | totalFrom | number | Minimum order total. | | totalTo | number | Maximum order total. | | createdFrom | number/string | Order placement datetime lower bound. | | createdTo | number/string | Order placement datetime upper bound. | | updatedFrom | number/string | Order update datetime lower bound. | | updatedTo | number/string | Order update datetime upper bound. | | paymentStatus | string | Payment status filter. Supports multiple comma-separated values: AWAITING_PAYMENT, PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, INCOMPLETE. | | fulfillmentStatus | string | Fulfillment status filter. Supports multiple comma-separated values: AWAITING_PROCESSING, PROCESSING, SHIPPED, DELIVERED, WILL_NOT_DELIVER, RETURNED, READY_FOR_PICKUP, OUT_FOR_DELIVERY. | | paymentMethod | string | Payment method name. | | shippingMethod | string | Shipping method name. | | couponCode | string | Discount coupon code applied to the order. | | offset | number | Pagination offset. | | limit | number | Max items to return (max/default: 100). | | responseFields | string | Limit response fields. Example: items(id,email,total,paymentStatus) |

Key response fields (items)

Field	Type	Description
INLINECODE126	string	Order ID (string, not number!) e.g. "ORD001", "XYZ99".
INLINECODE129

number | Internal numeric order ID. | | email | string | Customer email. | | total | number | Order total with all modifiers. | | subtotal | number | Cost of products before modifiers. | | tax | number | Sum of all taxes. | | couponDiscount | number | Discount from coupon. | | discount | number | Sum of all advanced discounts. | | paymentStatus | string | Payment status. | | fulfillmentStatus | string | Fulfillment status. | | paymentMethod | string | Payment method name. | | createDate | string | Order placement datetime. | | updateDate | string | Last update datetime. | | createTimestamp | number | Order placement UNIX timestamp. | | updateTimestamp | number | Last update UNIX timestamp. | | customerId | number | Internal customer ID. | | items | array | Products in the order (with productId, name, price, quantity, sku). | | shippingPerson | object | Shipping address (name, street, city, countryCode, postalCode, phone). | | billingPerson | object | Billing address (same fields as shippingPerson). | | shippingOption | object | Shipping details (shippingMethodName, shippingRate). | | trackingNumber | string | Shipping tracking code. | | privateAdminNotes | string | Private notes by store owner. | | orderComments | string | Customer's order comments. |

Example

CODEBLOCK7

Get single order

CODEBLOCK8

Returns the full order object directly. Note: orderId is a string (e.g. "ORD001"), not a number.

---

Customers

Scope required: INLINECODE166

Search/list customers

CODEBLOCK9

Query parameters

Name	Type	Description
INLINECODE167	string	Search customer name and email.
INLINECODE168

string | Search customer name (billingPerson.name). | | email | string | Search customer email. | | useExactEmailMatch | boolean | true for exact email match (requires email param). | | phone | string | Search customer phone number. | | city | string | Search customer city in shipping address. | | postalCode | string | Search customer ZIP code. | | stateOrProvinceCode | string | Two-digit state code. | | countryCodes | string | Country codes in shipping address. | | companyName | string | Company name in shipping address. | | acceptMarketing | boolean | Filter by marketing email acceptance. | | customerGroupIds | string | Customer group IDs (comma-separated). | | minOrderCount | number | Minimum number of customer orders. | | maxOrderCount | number | Maximum number of customer orders. | | minSalesValue | number | Minimum total order value. | | maxSalesValue | number | Maximum total order value. | | createdFrom | number/string | Registration datetime lower bound. | | createdTo | number/string | Registration datetime upper bound. | | updatedFrom | number/string | Last update datetime lower bound. | | updatedTo | number/string | Last update datetime upper bound. | | sortBy | string | One of: NAME_ASC, NAME_DESC, EMAIL_ASC, EMAIL_DESC, ORDER_COUNT_ASC, ORDER_COUNT_DESC, REGISTERED_DATE_DESC, REGISTERED_DATE_ASC, UPDATED_DATE_DESC, UPDATED_DATE_ASC, SALES_VALUE_ASC, SALES_VALUE_DESC. | | offset | number | Pagination offset. | | limit | number | Max items (max/default: 100). | | responseFields | string | Limit response fields. |

Key response fields (items)

Field	Type	Description
INLINECODE206	number	Internal customer ID.
INLINECODE207

string | Customer email. | | name | string | Customer name. | | totalOrderCount | number | Total orders placed. | | registered | string | Registration datetime. | | updated | string | Last update datetime. | | billingPerson | object | Billing name/address. | | shippingAddresses | array | Saved shipping addresses. | | contacts | array | Contact info (email, phone, social media). | | customerGroupId | number | Customer group ID. | | customerGroupName | string | Customer group name. | | taxExempt | boolean | Whether customer is tax exempt. | | acceptMarketing | boolean | Whether customer accepted marketing emails. | | stats | object | Sales stats: numberOfOrders, salesValue, averageOrderValue, firstOrderDate, lastOrderDate. | | privateAdminNotes | string | Private admin notes. |

The response also includes allCustomerCount (total unique customers in store) at the top level.

Example

CODEBLOCK10

Get single customer

CODEBLOCK11

Returns the full customer object directly. customerId is a number.

---

Categories

Scope required: INLINECODE228

Search/list categories

CODEBLOCK12

Query parameters

Name	Type	Description
INLINECODE229	string	Search category name and description.
INLINECODE230

number | Parent category ID — returns only direct children. | | parentIds | string | Comma-separated parent category IDs for descendants search. | | withSubcategories | boolean | true to get full category tree (subcategories of subcategories). | | hidden_categories | boolean | true to include disabled categories. | | offset | number | Pagination offset. | | limit | number | Max items (max/default: 100). | | responseFields | string | Limit response fields. |

Key response fields (items)

Field	Type	Description
INLINECODE239	number	Internal category ID.
INLINECODE240

number | Parent category ID. | | name | string | Category name. | | url | string | Full storefront URL. | | productCount | number | Products in category and subcategories. | | enabledProductCount | number | Enabled products (requires productIds=true). | | description | string | Category description (HTML). | | enabled | boolean | Whether category is enabled. | | imageUrl | string | Category image (1200px). | | thumbnailUrl | string | Category thumbnail (400px). | | orderBy | number | Sort order (starts from 10, increments by 10). | | productIds | array | Product IDs in category (requires productIds=true query param). |

Example

CODEBLOCK13

Get single category

CODEBLOCK14

Returns the full category object directly. categoryId is a number.

---

Discount Coupons

Scope required: INLINECODE254

Search/list coupons

CODEBLOCK15

Query parameters

Name	Type	Description
INLINECODE255	string	Search by coupon code.
INLINECODE256

string | Filter by type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING. | | availability | string | Filter by status: ACTIVE, PAUSED, EXPIRED, USEDUP. | | createdFrom | number/string | Creation date lower bound. | | createdTo | number/string | Creation date upper bound. | | updatedFrom | number/string | Update date lower bound. | | updatedTo | number/string | Update date upper bound. | | offset | number | Pagination offset. | | limit | number | Max items (max/default: 100). | | responseFields | string | Limit response fields. |

Key response fields (items)

Field	Type	Description
INLINECODE274	number	Internal coupon ID.
INLINECODE275

string | Coupon name. | | code | string | Coupon code used at checkout. | | discountType | string | Type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING. | | status | string | Status: ACTIVE, PAUSED, EXPIRED, USEDUP. | | discount | number | Discount value. | | launchDate | string | Coupon launch date. | | expirationDate | string | Coupon expiration date. | | totalLimit | number | Minimum order subtotal for coupon to apply. | | usesLimit | string | Uses limit: UNLIMITED, ONCEPERCUSTOMER, SINGLE. | | applicationLimit | string | Application limit: UNLIMITED, NEW_CUSTOMER_ONLY, REPEAT_CUSTOMER_ONLY. | | creationDate | string | Coupon creation date. | | updateDate | string | Last update date. | | orderCount | number | Number of orders using this coupon. | | catalogLimit | object | Product/category limitations (products, categories arrays). |

Example

CODEBLOCK16

Get single coupon

CODEBLOCK17

Returns the full coupon object directly. couponId is a number.

---

Promotions

Scope required: INLINECODE307

List promotions

CODEBLOCK18

Query parameters

Name	Type	Description
INLINECODE308	string	Limit response fields. Example: INLINECODE309

Note: Promotions endpoint has minimal filtering — only responseFields is supported.

Key response fields (items)

Field	Type	Description
INLINECODE311	number	Internal promotion ID.
INLINECODE312

string | Promotion name visible at checkout. | | enabled | boolean | Whether promotion is active. | | discountBase | string | Discount base: ITEM, SUBTOTAL, SHIPPING. | | discountType | string | Discount type: PERCENT, ABSOLUTE, FIXED_PRICE. | | amount | number | Discount amount. | | triggers | object | Trigger conditions (subtotal, startDate, endDate, customerGroups, minProductQuantityInCart, etc.). | | targets | object | Target limitations (categories, products, shippingMethods, etc.). |

Example

CODEBLOCK19

---

Abandoned Carts

Scope required: INLINECODE333

IMPORTANT: The endpoint path is /carts, NOT /abandoned_carts. Using /abandoned_carts returns a 404 error.

Search abandoned carts

CODEBLOCK20

Query parameters

Name	Type	Description
INLINECODE337	boolean	Set false to exclude deleted carts.
INLINECODE339

number | Minimum cart total. | | totalTo | number | Maximum cart total. | | createdFrom | number/string | Cart creation datetime lower bound. | | createdTo | number/string | Cart creation datetime upper bound. | | updatedFrom | number/string | Cart update datetime lower bound. | | updatedTo | number/string | Cart update datetime upper bound. | | email | string | Customer email. | | customerId | number | Customer's internal ID. | | offset | number | Pagination offset. | | limit | number | Max items (max: 100, default: 10). | | responseFields | string | Limit response fields. Example: items(cartId,total,email) |

Key response fields (items)

Field	Type	Description
INLINECODE351	string	Unique cart ID (UUID format), e.g. "6626E60A-A6F9-4CD5-8230-43D5F162E0CD".
INLINECODE353

string | Customer email. | | total | number | Cart total. | | subtotal | number | Cart subtotal. | | tax | number | Total tax. | | createDate | string | Cart creation datetime. | | updateDate | string | Last update datetime. | | createTimestamp | number | Creation UNIX timestamp. | | updateTimestamp | number | Last update UNIX timestamp. | | customerId | number | Internal customer ID. | | paymentMethod | string | Selected payment method. | | items | array | Products in cart (productId, name, price, quantity, sku). | | billingPerson | object | Billing address. | | shippingPerson | object | Shipping address. | | shippingOption | object | Selected shipping option. | | couponDiscount | number | Discount from coupon. | | discount | number | Sum of all advanced discounts. | | recoveredOrderId | number | Order ID if cart was recovered. | | hidden | boolean | Whether cart is hidden from admin. |

Example

CODEBLOCK21

Get single abandoned cart

CODEBLOCK22

Returns the full cart object directly. cartId is a string (UUID format).

---

Store Profile

Scope required: INLINECODE377

Get store profile

CODEBLOCK23

Returns store settings including general info, company details, languages, currencies, tax settings, and more.

No query parameters required (supports responseFields for filtering).

Example

CODEBLOCK24

---

Quick Reference

Resource	List Endpoint	Single Endpoint	Scope
Products	INLINECODE379	INLINECODE380	INLINECODE381
Orders

GET /orders | GET /orders/{orderId} | read_orders |
| Customers | GET /customers | GET /customers/{customerId} | read_customers |
| Categories | GET /categories | GET /categories/{categoryId} | read_catalog |
| Coupons | GET /discount_coupons | GET /discount_coupons/{couponId} | read_discount_coupons |
| Promotions | GET /promotions | — | read_promotion |
| Abandoned Carts | GET /carts | GET /carts/{cartId} | read_orders |
| Store Profile | GET /profile | — | read_store_profile |

ID Types

Resource	ID Type	Example
Products	number	INLINECODE401
Orders

string | "ORD001" | | Customers | number | 177737165 | | Categories | number | 9691094 | | Coupons | number | 162428889 | | Abandoned Carts | string (UUID) | "6626E60A-A6F9-4CD5-8230-43D5F162E0CD" |