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:

SettingValueService nameEcwidBase URLhttps://app.ecwid.com/api/v3/{storeId} (replace {storeId} with your actual store ID)Auth typeBearer tokenTokenYour store's secret API token (format: secret_xxxxx)HTTP methodsGET 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

NameTypeDescriptionkeywordstringSearch term. Searches name, description, SKU, options, category name, gallery image descriptions, attribute values. Add * at end to disable exact match.productIdnumberInternal product IDs (comma-separated). If set, other search params are ignored.skustringExact product or variation SKU match. If set, other params ignored except productId.categorystringCategory ID to filter products by.categoriesstringComma-separated category IDs, e.g. 0,123456,138470508.includeProductsFromSubcategoriesbooleanSet true to include products from subcategories.priceFromnumberMinimum product price.priceTonumberMaximum product price.createdFromnumber/stringProduct creation date lower bound.createdTonumber/stringProduct creation date upper bound.updatedFromnumber/stringProduct update date lower bound.updatedTonumber/stringProduct update date upper bound.enabledbooleantrue for enabled only, false for disabled only.inStockbooleantrue for in-stock only, false for out-of-stock only.sortBystringOne 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.offsetnumberPagination offset.limitnumberMax items to return (max/default: 100).responseFieldsstringLimit response fields. Example: items(id,name,price,sku)

Key response fields (items)

FieldTypeDescriptionidnumberInternal product ID.skustringProduct SKU.namestringProduct name.pricenumberBase product price.defaultDisplayedPricenumberPrice shown on storefront (includes taxes).compareToPricenumberPre-sale / "compare to" price.quantitynumberStock quantity (absent if unlimited is true).unlimitedbooleanWhether product has unlimited stock.inStockbooleanWhether in stock.enabledbooleanWhether visible on storefront.weightnumberProduct weight.urlstringStorefront product page URL.createdstringCreation datetime.updatedstringLast update datetime.createTimestampnumberCreation UNIX timestamp.updateTimestampnumberLast update UNIX timestamp.descriptionstringProduct description (HTML).categoryIdsarrayIDs of assigned categories.defaultCategoryIdnumberDefault category ID.imageUrlstringMain image URL (1200px).thumbnailUrlstringThumbnail URL (400px).originalImageUrlstringFull-size image URL.optionsarrayProduct options (size, color, etc.).combinationsarrayProduct variations.attributesarrayProduct attributes and values.isGiftCardbooleanWhether 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

NameTypeDescriptionidsstringComma-separated order IDs, internal IDs, prefixes, and suffixes. Example: EG4H2,J77J8``keywordsstringSearch order ID, transaction ID, addresses, email, tracking code, item SKUs/names, admin notes.emailstringCustomer email.customerIdnumberCustomer's internal ID.productIdnumber/stringProduct IDs in order (comma-separated).totalFromnumberMinimum order total.totalTonumberMaximum order total.createdFromnumber/stringOrder placement datetime lower bound.createdTonumber/stringOrder placement datetime upper bound.updatedFromnumber/stringOrder update datetime lower bound.updatedTonumber/stringOrder update datetime upper bound.paymentStatusstringPayment status filter. Supports multiple comma-separated values: AWAITING_PAYMENT, PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, INCOMPLETE.fulfillmentStatusstringFulfillment status filter. Supports multiple comma-separated values: AWAITING_PROCESSING, PROCESSING, SHIPPED, DELIVERED, WILL_NOT_DELIVER, RETURNED, READY_FOR_PICKUP, OUT_FOR_DELIVERY.paymentMethodstringPayment method name.shippingMethodstringShipping method name.couponCodestringDiscount coupon code applied to the order.offsetnumberPagination offset.limitnumberMax items to return (max/default: 100).responseFieldsstringLimit response fields. Example: items(id,email,total,paymentStatus)

Key response fields (items)

FieldTypeDescriptionidstringOrder ID (string, not number!) e.g. "ORD001", "XYZ99".internalIdnumberInternal numeric order ID.emailstringCustomer email.totalnumberOrder total with all modifiers.subtotalnumberCost of products before modifiers.taxnumberSum of all taxes.couponDiscountnumberDiscount from coupon.discountnumberSum of all advanced discounts.paymentStatusstringPayment status.fulfillmentStatusstringFulfillment status.paymentMethodstringPayment method name.createDatestringOrder placement datetime.updateDatestringLast update datetime.createTimestampnumberOrder placement UNIX timestamp.updateTimestampnumberLast update UNIX timestamp.customerIdnumberInternal customer ID.itemsarrayProducts in the order (with productId, name, price, quantity, sku).shippingPersonobjectShipping address ( name, street, city, countryCode, postalCode, phone).billingPersonobjectBilling address (same fields as shippingPerson).shippingOptionobjectShipping details ( shippingMethodName, shippingRate).trackingNumberstringShipping tracking code.privateAdminNotesstringPrivate notes by store owner.orderCommentsstringCustomer'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

NameTypeDescriptionkeywordstringSearch customer name and email.namestringSearch customer name ( billingPerson.name).emailstringSearch customer email.useExactEmailMatchbooleantrue for exact email match (requires email param).phonestringSearch customer phone number.citystringSearch customer city in shipping address.postalCodestringSearch customer ZIP code.stateOrProvinceCodestringTwo-digit state code.countryCodesstringCountry codes in shipping address.companyNamestringCompany name in shipping address.acceptMarketingbooleanFilter by marketing email acceptance.customerGroupIdsstringCustomer group IDs (comma-separated).minOrderCountnumberMinimum number of customer orders.maxOrderCountnumberMaximum number of customer orders.minSalesValuenumberMinimum total order value.maxSalesValuenumberMaximum total order value.createdFromnumber/stringRegistration datetime lower bound.createdTonumber/stringRegistration datetime upper bound.updatedFromnumber/stringLast update datetime lower bound.updatedTonumber/stringLast update datetime upper bound.sortBystringOne 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.offsetnumberPagination offset.limitnumberMax items (max/default: 100).responseFieldsstringLimit response fields.

Key response fields (items)

FieldTypeDescriptionidnumberInternal customer ID.emailstringCustomer email.namestringCustomer name.totalOrderCountnumberTotal orders placed.registeredstringRegistration datetime.updatedstringLast update datetime.billingPersonobjectBilling name/address.shippingAddressesarraySaved shipping addresses.contactsarrayContact info (email, phone, social media).customerGroupIdnumberCustomer group ID.customerGroupNamestringCustomer group name.taxExemptbooleanWhether customer is tax exempt.acceptMarketingbooleanWhether customer accepted marketing emails.statsobjectSales stats: numberOfOrders, salesValue, averageOrderValue, firstOrderDate, lastOrderDate.privateAdminNotesstringPrivate 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=john@example.com' \
  -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

NameTypeDescriptionkeywordstringSearch category name and description.parentnumberParent category ID — returns only direct children.parentIdsstringComma-separated parent category IDs for descendants search.withSubcategoriesbooleantrue to get full category tree (subcategories of subcategories).hidden_categoriesbooleantrue to include disabled categories.offsetnumberPagination offset.limitnumberMax items (max/default: 100).responseFieldsstringLimit response fields.

Key response fields (items)

FieldTypeDescriptionidnumberInternal category ID.parentIdnumberParent category ID.namestringCategory name.urlstringFull storefront URL.productCountnumberProducts in category and subcategories.enabledProductCountnumberEnabled products (requires productIds=true).descriptionstringCategory description (HTML).enabledbooleanWhether category is enabled.imageUrlstringCategory image (1200px).thumbnailUrlstringCategory thumbnail (400px).orderBynumberSort order (starts from 10, increments by 10).productIdsarrayProduct 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

NameTypeDescriptioncodestringSearch by coupon code.discount_typestringFilter by type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING.availabilitystringFilter by status: ACTIVE, PAUSED, EXPIRED, USEDUP.createdFromnumber/stringCreation date lower bound.createdTonumber/stringCreation date upper bound.updatedFromnumber/stringUpdate date lower bound.updatedTonumber/stringUpdate date upper bound.offsetnumberPagination offset.limitnumberMax items (max/default: 100).responseFieldsstringLimit response fields.

Key response fields (items)

FieldTypeDescriptionidnumberInternal coupon ID.namestringCoupon name.codestringCoupon code used at checkout.discountTypestringType: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING.statusstringStatus: ACTIVE, PAUSED, EXPIRED, USEDUP.discountnumberDiscount value.launchDatestringCoupon launch date.expirationDatestringCoupon expiration date.totalLimitnumberMinimum order subtotal for coupon to apply.usesLimitstringUses limit: UNLIMITED, ONCEPERCUSTOMER, SINGLE.applicationLimitstringApplication limit: UNLIMITED, NEW_CUSTOMER_ONLY, REPEAT_CUSTOMER_ONLY.creationDatestringCoupon creation date.updateDatestringLast update date.orderCountnumberNumber of orders using this coupon.catalogLimitobjectProduct/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

NameTypeDescriptionresponseFieldsstringLimit response fields. Example: items(name,enabled)

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

Key response fields (items)

FieldTypeDescriptionidnumberInternal promotion ID.namestringPromotion name visible at checkout.enabledbooleanWhether promotion is active.discountBasestringDiscount base: ITEM, SUBTOTAL, SHIPPING.discountTypestringDiscount type: PERCENT, ABSOLUTE, FIXED_PRICE.amountnumberDiscount amount.triggersobjectTrigger conditions ( subtotal, startDate, endDate, customerGroups, minProductQuantityInCart, etc.).targetsobjectTarget 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

NameTypeDescriptionshowHiddenbooleanSet false to exclude deleted carts.totalFromnumberMinimum cart total.totalTonumberMaximum cart total.createdFromnumber/stringCart creation datetime lower bound.createdTonumber/stringCart creation datetime upper bound.updatedFromnumber/stringCart update datetime lower bound.updatedTonumber/stringCart update datetime upper bound.emailstringCustomer email.customerIdnumberCustomer's internal ID.offsetnumberPagination offset.limitnumberMax items (max: 100, default: 10).responseFieldsstringLimit response fields. Example: items(cartId,total,email)

Key response fields (items)

FieldTypeDescriptioncartIdstringUnique cart ID (UUID format), e.g. "6626E60A-A6F9-4CD5-8230-43D5F162E0CD".emailstringCustomer email.totalnumberCart total.subtotalnumberCart subtotal.taxnumberTotal tax.createDatestringCart creation datetime.updateDatestringLast update datetime.createTimestampnumberCreation UNIX timestamp.updateTimestampnumberLast update UNIX timestamp.customerIdnumberInternal customer ID.paymentMethodstringSelected payment method.itemsarrayProducts in cart ( productId, name, price, quantity, sku).billingPersonobjectBilling address.shippingPersonobjectShipping address.shippingOptionobjectSelected shipping option.couponDiscountnumberDiscount from coupon.discountnumberSum of all advanced discounts.recoveredOrderIdnumberOrder ID if cart was recovered.hiddenbooleanWhether cart is hidden from admin.

Example

text

curl 'https://app.ecwid.com/api/v3/1003/carts?email=customer@example.com' \
  -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#

ResourceList EndpointSingle EndpointScopeProductsGET /products``GET /products/{productId}``read_catalogOrdersGET /orders``GET /orders/{orderId}``read_ordersCustomersGET /customers``GET /customers/{customerId}``read_customersCategoriesGET /categories``GET /categories/{categoryId}``read_catalogCouponsGET /discount_coupons``GET /discount_coupons/{couponId}``read_discount_couponsPromotionsGET /promotions—read_promotionAbandoned CartsGET /carts``GET /carts/{cartId}``read_ordersStore ProfileGET /profile—read_store_profile

ID Types#

ResourceID TypeExampleProductsnumber12345678Ordersstring"ORD001"Customersnumber177737165Categoriesnumber9691094Couponsnumber162428889Abandoned Cartsstring (UUID)"6626E60A-A6F9-4CD5-8230-43D5F162E0CD"