About Ecwid REST API

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:

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 data
  • PUT to update store data
  • POST to create entries
  • DELETE 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 to 2023-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 productIds), specify them in a corresponding filter – productId. More details: Searching Products
  • To get multiple order details at once (knowing their orderNumbers), 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