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:

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:

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

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

Authentication

All requests require the Authorization header:

Authorization: Bearer secret_xxxxx

Products

Scope required: read_catalog

Search/list products

GET /products

Query parameters

Key response fields (items)

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

Key response fields (items)

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

Key response fields (items)

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

Key response fields (items)

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

Key response fields (items)

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

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

Key response fields (items)

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

Key response fields (items)

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

ID Types