Ecwid Ecommerce

Ecwid REST API v3 integration for managing e-commerce store data including products, orders, customers, categories, discount coupons, promotions, abandoned carts, and store profile. Use when the user wants to interact with their Ecwid online store.

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. 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:

json

{
  "total": 150,
  "count": 100,
  "offset": 0,
  "limit": 100,
  "items": [...]
}

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:

text

?responseFields=total,items(id,name,price)

This reduces response size and speeds up requests.

Date formats

Date parameters accept both:

• UNIX timestamps: 1447804800
• Datetime strings: 2023-01-15 19:27:50

Authentication

All requests require the Authorization header:

text

Authorization: Bearer secret_xxxxx

---

Products

Scope required: read_catalog

Search/list products

text

GET /products

Query parameters

Name	Type	Description
keyword	string	Search term. Searches name, description, SKU, options, category name, gallery image descriptions, attribute values. Add * at end to disable exact match.
productId	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
id	number	Internal product ID.
sku	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

text

curl 'https://app.ecwid.com/api/v3/1003/products?keyword=drone&limit=10' \
  -H 'Authorization: Bearer secret_token'

Get single product

text

GET /products/{productId}

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

---

Orders

Scope required: read_orders

Search/list orders

text

GET /orders

Query parameters

Name	Type	Description
ids	string	Comma-separated order IDs, internal IDs, prefixes, and suffixes. Example: EG4H2,J77J8
keywords	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
id	string	Order ID (string, not number!) e.g. "ORD001", "XYZ99".
internalId	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

text

curl 'https://app.ecwid.com/api/v3/1003/orders?paymentStatus=PAID&fulfillmentStatus=DELIVERED&limit=10' \
  -H 'Authorization: Bearer secret_token'

Get single order

text

GET /orders/{orderId}

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

---

Customers

Scope required: read_customers

Search/list customers

text

GET /customers

Query parameters

Name	Type	Description
keyword	string	Search customer name and email.
name	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
id	number	Internal customer ID.
email	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

text

curl 'https://app.ecwid.com/api/v3/1003/customers?email=[e-mail]' \
  -H 'Authorization: Bearer secret_token'

Get single customer

text

GET /customers/{customerId}

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

---

Categories

Scope required: read_catalog

Search/list categories

text

GET /categories

Query parameters

Name	Type	Description
keyword	string	Search category name and description.
parent	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
id	number	Internal category ID.
parentId	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

text

curl 'https://app.ecwid.com/api/v3/1003/categories?parent=0' \
  -H 'Authorization: Bearer secret_token'

Get single category

text

GET /categories/{categoryId}

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

---

Discount Coupons

Scope required: read_discount_coupons

Search/list coupons

text

GET /discount_coupons

Query parameters

Name	Type	Description
code	string	Search by coupon code.
discount_type	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
id	number	Internal coupon ID.
name	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

text

curl 'https://app.ecwid.com/api/v3/1003/discount_coupons?availability=ACTIVE' \
  -H 'Authorization: Bearer secret_token'

Get single coupon

text

GET /discount_coupons/{couponId}

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

---

Promotions

Scope required: read_promotion

List promotions

text

GET /promotions

Query parameters

Name	Type	Description
responseFields	string	Limit response fields. Example: items(name,enabled)

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

Key response fields (items)

Field	Type	Description
id	number	Internal promotion ID.
name	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

text

curl 'https://app.ecwid.com/api/v3/1003/promotions' \
  -H 'Authorization: Bearer secret_token'

---

Abandoned Carts

Scope required: read_orders

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

Search abandoned carts

text

GET /carts

Query parameters

Name	Type	Description
showHidden	boolean	Set false to exclude deleted carts.
totalFrom	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
cartId	string	Unique cart ID (UUID format), e.g. "6626E60A-A6F9-4CD5-8230-43D5F162E0CD".
email	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

text

curl 'https://app.ecwid.com/api/v3/1003/carts?email=[e-mail]' \
  -H 'Authorization: Bearer secret_token'

Get single abandoned cart

text

GET /carts/{cartId}

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

---

Store Profile

Scope required: read_store_profile

Get store profile

text

GET /profile

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

No query parameters required (supports responseFields for filtering).

Example

text

curl 'https://app.ecwid.com/api/v3/1003/profile' \
  -H 'Authorization: Bearer secret_token'

---

Quick Reference

Resource	List Endpoint	Single Endpoint	Scope
Products	GET /products	GET /products/{productId}	read_catalog
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	12345678
Orders	string	"ORD001"
Customers	number	177737165
Categories	number	9691094
Coupons	number	162428889
Abandoned Carts	string (UUID)	"6626E60A-A6F9-4CD5-8230-43D5F162E0CD"