Ecwid Ecommerce

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

Common Patterns

Pagination

All list endpoints return the same pagination envelope:

{
  "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:

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

This reduces response size and speeds up requests.

Date formats

Date parameters accept both:

Authentication

All requests require the Authorization header:

Authorization: Bearer secret_xxxxx

Products

Scope required: read_catalog

Search/list products

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

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

Get single product

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

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

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

Get single order

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

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

curl 'https://app.ecwid.com/api/v3/1003/customers?email=john@example.com' \
  -H 'Authorization: Bearer secret_token'

Get single customer

GET /customers/{customerId}

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

Categories

Scope required: read_catalog

Search/list categories

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

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

Get single category

GET /categories/{categoryId}

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

Discount Coupons

Scope required: read_discount_coupons

Search/list coupons

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

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

Get single coupon

GET /discount_coupons/{couponId}

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

Promotions

Scope required: read_promotion

List promotions

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

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

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

curl 'https://app.ecwid.com/api/v3/1003/carts?email=customer@example.com' \
  -H 'Authorization: Bearer secret_token'

Get single abandoned cart

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

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

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" |

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

Get single product

GET /products/{productId}

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