Ecwid REST API allows your application to manage Ecwid store on behalf of an Ecwid user. Create products, update orders, delete a customer and many many more.
Available endpoints:
- Store profile
- Products
- Categories
- Product variations
- Product types
- Orders
- Carts
- Customers
- Customer groups
- Discount coupons
- Application status
API basics
RESTful / oAuth2
Ecwid API is a RESTful API with oAuth2 authentication. As any RESTful service, Ecwid REST API use the standard HTTP codes in requests:
GET
to read store dataPUT
to update store dataPOST
to create entriesDELETE
to remove entries
HTTPS
All requests are done via HTTPs. Requests via insecure HTTP are not supported.
UTF-8
Ecwid API works with UTF-8 encoded data. Please make sure everything you send over in API calls also uses UTF-8.
Content Type
All data received from API and submitted to API is JSON, so the content type should be: application/json;charset=utf-8
Accept Encoding
You can use optional header Accept-Encoding: gzip
to get responses from the Ecwid REST API quicker. This header tells Ecwid to provide compressed version of the response, thus it improves the speed of the responses.
UTC
Date/time values returned by Ecwid API are in UTC.
API Version
This document describes Ecwid REST API v.3
Date/Time formats
Supported formats:
- UNIX timestamp
- yyyy-MM-dd HH:mm:ss Z
- yyyy-MM-dd HH:mm:ss
- yyyy-MM-dd
Examples:
1447804800
2023-04-22 18:48:38 -0500
2023-04-22
(equal to2023-04-22 00:00:00 UTC
)
For ease of understanding and access, only UNIX timestamp format is described in the endpoint documentation.
Response fields specification
By default, Ecwid REST API responds to GET requests with all available fields, which can make requests quite heavy and time-consuming.
However, it is possible to specify what fields you want to receive with the responseFields
parameter. Example: https://app.ecwid.com/api/v3/STOREID/orders?responseFields=items(id,total)
In the example case, fields "id" and "total" are inside the "items" object and therefore are written in brackets.
API calls limits
Ecwid REST API has the following limits:
- 600 requests per minute per one store's token
If you go over the limit, you'll receive a 429 error and your token will be temporarily blocked. Use Batch API requests to stay inside request limits.
In case your token is no longer valid, limits are:
- 20 requests per minute for the specific store
- 600 requests per IP
If you surpass these limits, Ecwid will block the "token+IP" pair or the IP making these requests respectively.
Usage policy
To protect us and our users from abusing, we strongly advise that you optimize your app code to make fewer API requests. For example:
- Cache store data locally if you need to use or display it many times in your app
- If you need to synchronize store data with your database, use Webhooks to get timely updates about changes in a store. More details: Webhooks
- To get multiple product details at once (knowing their
productId
s), specify them in a corresponding filter –productId
. More details: Searching Products - To get multiple order details at once (knowing their
orderNumber
s), specify them in a corresponding filter –orderNumber
. More details: Searching Orders
We constantly monitor API activity and servers load on our side to make sure every application uses API properly. In case an app abuses Ecwid API by generating huge amount of requests every day, we'll get in touch with you to talk about this issue.
Don't worry, you will unlikely face such trouble and even if you do, we will advice on how to fix that. But of course, if the usage is high enough to significantly affect other users of the platform and you don't react on our warnings, we can temporarily disable your application.
How to make requests?
You can use any library or software (capable of making HTTP requests) you are familiar with.
To make a basic API request you will need to know:
- Ecwid Store ID
- Access token. We use bearer token included in the authorization header of an HTTP request.
These details are provided at the end of the app installation in an Ecwid store. Ways to get them depend on the app you are using, see the Authentication basics for more details.
Using REST API in storefront
When working on a custom storefront functionality, applications can require getting up-to-date catalog information from Ecwid store.
var xhttp = new XMLHttpRequest();
var storeId = 1003;
var token = 'Bearer public_qKDUqKkNXzcj9DejkMUqEkYLq2E6BXM9';
var requestURL = 'https://app.ecwid.com/api/v3/'+storeId+'/products?&limit=3';
xhttp.open("GET", requestURL, true);
xhttp.setRequestHeader("Authorization", token)
xhttp.send();
xhttp.onreadystatechange = function() {
if (xhttp.readyState == 4 && xhttp.status == 200) {
var apiResponse = xhttp.responseText;
console.log(apiResponse); // prints response in format of Search Products request in Ecwid API
}
};
With public access token you can safely make requests to Ecwid REST API without compromising store security. You can make an Ajax request to Ecwid API with your JavaScript code and have a completely serverless application.
If you have to use private token, create a buffer on server-side (via PHP, etc.), which requests information for your client-side code (JS).
For more information on using custom JavaScript in Ecwid storefront, see Customize behaviour section