Ecwid REST API grants access to the store data including products, orders, customers, discounts and many more. Everything you can find in the store Control Panel is available through the code with REST API: reading customers data, creating new products, order status updates, etc.
Sign up with Ecwid
To start working with Ecwid API, you need a store on any paid plan. Sign up with Ecwid.
We will provide you with a free test store with API access if you:
- Work on a customization for one of our clients
- Want to develop a customization for your working store in a safe environment
- Develop a public application for our App Market
Email us to get a test store.
Set up an application
API access requires a platform where you can configure permissions and generate tokens. In Ecwid we refer to this platform as an application. A private application that gives you access to your store data through API is referred to as a custom application.
Set up a custom application in your Ecwid Control Panel, it only takes a few seconds: #develop-apps
Application grants you control over API access which is defined by the following settings you'll see on the Details page:
- Access scopes - list of app permissions for making different requests. For example, read_orders scope is required for the "Get orders" request, update_customers is required for "Update customer", etc. Find the full list of available access scopes below.
- Access token - authorization key for REST API requests. Access tokens don't expire and contain a list of scopes inside. There are two token types: secret_token and public_token.
- public_token is used to get publically available data with GET requests: public profile details and enabled products/categories data. It is safe to use on the storefront.
- secret_token allows making all requests. Do not use it in publically available code to keep store data safe.
- Endpoint - external URL where Ecwid sends requests for some APIs. For example, webhooks, payment and shipping requests.
Start making requests
Any REST API request needs at least store ID and token for authorization.
You already have the app with access tokens. Copy your access token, then scroll Control Panel page to the bottom and find your store ID in the footer.
To make a simple "Get orders" request, add store ID to the request URL path and a token to the header, then execute it.
Request example:
curl --location 'https://app.ecwid.com/api/v3/STOREID/orders' \
--header 'Authorization: Bearer SECRET_TOKEN'
You'll receive a response with JSON object in the body:
{
"total": 1,
"items": [
{
"id": "EBJFT",
"total": 600,
"email": "[email protected]",
"discount": 0,
"items": [ ... ]
}
]
}
Features availability
Ecwid API is available on any paid plan. With API you can access all features active on the current store plan. See: Plans and features
Rate limits
You can make up to 600 requests per minute with one application token which becomes temporarily blocked if you exceed the limit. API responds with error 429 to all requests at that time.
In case a token is no longer valid, the limits are:
- 20 requests per minute per token
- 600 requests per IP
Ecwid will permanently block the token and IP pair if you exceed them.
Access scopes
Access scopes define app permissions for making different REST API requests and accessing different APIs like Payment API. One application can have any set of scopes that allows apps to be multifunctional.
In the documentation, all features and endpoints have a block with access scope requirements. Here you can check all access scopes available in Ecwid API. If you want to add new scopes to your custom application, please email us with your application name and a list of required scopes. We'll update your app shortly.
| Access scope | Notes |
|---|---|
| read_store_profile | Get store name and general settings, get store admin email, get updated statistics, etc. Requested in all cases even if not specified |
| update_store_profile | Set taxes, update invoice logo, change Starter Site domain, close store for maintenance, etc. |
| read_store_limits | Get store limits and restrictions, e.g. maximum number of available products. |
| read_catalog | Search products, get product options/variations etc. Also allows receiving push updates (webhooks) about changes in-store products. |
| update_catalog | Update product prices, upload images, and e-goods, modify product attributes, delete products and categories, etc. |
| create_catalog | Create new products |
| read_orders | Get sales for a given period, retrieve order details, etc. Also allows receiving push updates (webhooks) about changes in-store orders. |
| update_orders | Change order totals, switch order status, cancel orders, delete orders, etc. Requires read_orders scope to function |
| create_orders | Place a new order in the store |
| read_customers | Search customers or retrieve some particular customer data |
| update_customers | Change customer profile data, add items to the customer address book, delete customers, etc. |
| create_customers | Add a new customer to the store's Customers list |
| read_discount_coupons | Get the list of discount coupons or retrieve some particular coupon details |
| update_discount_coupons | Change the coupon expiration date or limit its number of use, update coupon code, delete coupon codes, etc. |
| create_discount_coupons | Add a new discount coupon |
| customize_storefront | Attach a custom JS/CSS to the storefront on the fly to modify its look and feel (see Customize appearance) |
| add_to_cp | Add a new tab to merchant control panel (see Embedding apps) |
| add_shipping_method | Add a new shipping method to the store (see Add shipping method) |
| add_payment_method | Add a new payment method to the store (see Add payment method) |
| public_storefront | Get public store details with the public access token |
| customize_cart_calculation | Apply custom discounts to orders in real-time (See Add custom discount) |
| read_invoices | Get the invoices. Allows receiving push updates (webhooks) about creating and deleting store invoices. |
| charge | Charge through Ecwid billing. Required for the Charge requests via an app. |
| read_store_stats | Get a store's statistic information |
| read_staff | Get information about staff accounts in a store |
| invite_staff | Send and resend staff account invites |
| delete_staff | Revoke sent invitation and delete staff account |
| read_subscriptions | Allows to get information about subscriptions |
| update_subscriptions | Allows update the details of subscriptions |
| read_brands | Allows to search product brands |