NAV

Overview

The documentation below describes various ways to interact with the Ecwid store by using the API. In each section you can find a detailed description, as well as code examples for managing store data that will help you create your own application.

To find out more about the Ecwid platform and get some basic details about it, please visit the Get Started page.

Learn more on how to start developing an app here: https://developers.ecwid.com/developing-your-app

API features

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.

Check out all available methods: REST API

Native Apps

Will your app have a settings page for a user to update them quickly? Place it right in Ecwid Control Panel! It is a great way to put your app up front to the users and let them use if more often.

More information: Native applications

Webhooks

Webhooks allow you to get an instant notification after an event ocurred in an Ecwid store. Send information to accounting right after an order was placed, send a note after a product was updated - it’s totally up to you.

More information: Webhooks

Add Shipping Methods

Custom Shipping API allows you to add new shipping methods in an Ecwid store as if they were available out of the box. Merchant can configure the integration in Ecwid Control Panel and new shipping methods will be displayed at checkout for store customers.

More information: Custom Shipping API

Find out more about Ecwid Platform:

https://developers.ecwid.com/intro

Add Payment Method

Custom Payment API allows you to add new payment methods to an Ecwid store. Merchant will install your app, set it up and they will be able to accept payments through your payment system for orders in their store.

More information: Custom Payment API

Apply Custom Discount

Custom Discount API allows you to apply a custom discount amount to an order being placed at the moment. Merchant can configure the discount rules in their Ecwid Control Panel using the Native apps feature and customers will have discounts on their orders according to those rules at checkout.

More information: Custom Discount API

Application Storage

Application storage is a key/value storage that can serve as a database for your application and a way to send details to user’s storefront. All data is kept on Ecwid servers, so you don’t need to worry about keeping the data safe.

More information: Application storage

Storefront customization

Ecwid has a beautifully designed storefront that is aimed to direct customers to make a purchase in a store. If you want to customize how it looks or its logic - you can do that too: attach an external Javascript file or adapt a store to make it stylish.

More information: Customize Storefront

Storefront Single Sign-On

Ecwid is a widget, that can be inserted to any website. Many websites have their own login functionality as well as Ecwid. To allow customers to sign in to their account in storefront automatically right after they sign in to merchant’s website or service, use Single Sign-On feature. It will save customers’ time and let them concentrate on shopping in the store.

More information: Storefront Single Sign-On

Applications for Ecwid

In Ecwid there can be two main categories of applications: Native and External apps.

Check out app examples

https://developers.ecwid.com/examples

Native apps

Native applications work inside of Ecwid Control Panel in a separate tab, just like Shipping Settings or Design. This way of embedding your app into user interface puts your app right before the day-to-day workflow of an Ecwid store owner and it is a great way to design an app for Ecwid. Using Ecwid JS SDK it’s very easy to get access token for a store.

More details: Native apps

External apps

External applications work outside of Ecwid Control panel and user would interact and control them on a separate website. This approach is great for applications that provide extensive feature set for store owners and would require implementing oAuth flow to get access token for a specific Ecwid store.

More details: External apps.

Use cases

Social marketing

Create an application that will get product details from an Ecwid store and provide user option to share and schedule posts to social media accounts with products from their Ecwid store.

Suggested API requests:

Product marketplace

Get product details from an Ecwid store to display them on a marketplace. Use webhooks to notify marketplace about changes of a product.

Suggested API features:

Fulfillment service

Synchronize Ecwid catalog with the fulfillment service of your choice. Update stock levels in both systems based on new orders in the store.

Suggested API features:

Affiliate program

Get information about new orders and provide commissions to your ambassadors. Use webhooks to get order details after it was placed.

Suggested API features:

Custom content in storefront

Create an app to show custom content in Ecwid storefront. Store owner can update it using your app interface in Ecwid Control Panel.

Suggested API features:

Membership system for customers

Use customer groups in the store as a tool to manage memberships. Provide discounts to regular shoppers like absolute discount or free shipping.

Suggested API features:

Storefront Themes

Customizing Ecwid’s design never been easier - apply your CSS file to all storefronts of a specific store. Help Ecwid users adapt the design of their storefront for their business or a website.

Suggested API features:

Learn more on how to create a theme for Ecwid: https://developers.ecwid.com/how-to-create-a-theme-for-an-ecwid-store

API availability on Ecwid plans

Ecwid pricing includes four tiers: Free, Venture, Business, Unlimited. The API is available on paid Ecwid plans, i.e. on Venture, Business and Unlimited. Merchants on Free plans cannot use Ecwid API. This means that, if the user is on Free plan, all API functions will fail including requests to read or update store data, embedding of the app interfaces into Ecwid Control Panel and customizing storefront.

Find out more about what you need to get started with Ecwid API

https://developers.ecwid.com/developing-your-app

Q: I need to start developing my app. How can I get a paid account?

If you’re building an app for Ecwid App Market, we would be happy to provide you with a paid Ecwid account for free for development and testing purposes. Feel free to contact us, provide the details of your application and we will help you.

Please note that this account must not be used for selling the application or any other products to real customers.

API playground

To quickly learn Ecwid API and see it in action even before you start development of your application, you can use Ecwid API playground. The playground is basically a collection of presets for PostMan. You can load it in PostMan application and try accessing and managing your store data via API.

Using the playground is easy. All you will need is:

  • “PostMan” Chrome extension (it’s free) . You can download it here
  • An Ecwid store which has access to API (the store needs to be on a paid plan)

To get more details and install the playground, please open this page: api-playground.ecwid.com

Authentication

Overview

The Ecwid platform provides two ways of installing and operating applications in an online store: native and external apps.

Native apps work solely in the Ecwid Control Panel by adding a new tab into one of its sections. When a user visits that tab, Ecwid will load the app page in an IFRAME window. The app can interact with a store (get access token, get store information) and with the Ecwid Control Panel using Ecwid JS SDK.

External apps work outside of the Ecwid Control Panel on an external website or in the background with no setup required. These applications need to handle the oAuth process themselves in order to get an access token. Usually, they work on the server side with their own database to store the access tokens of their users’ stores.

Access tokens

All Ecwid REST API requests require authentication. Ecwid supports oAuth2 protocol to provide applications with an easy way to authenticate and access store data on behalf of the user with access tokens.

There are two types of access tokens in Ecwid: private and public tokens. Private ones can’t be shared publicly as they provide access to modify store data through the REST API. Public tokens on the other hand have read-only access, so they can be used anywhere to get store details through the REST API in your apps.

Ecwid user grants or denies access to certain data in their store for the particular application - then the application gets its own secure access token (and optional public token) upon authorization and uses that token as a key to make REST API calls to Ecwid.

Private access token

Private access token example

{
    "access_token": "secure_adasjkhndjksnmkasjhdASDHasjdnhasa"
}

Private access token provides access to Ecwid API to retrieve and change store data on behalf of the user who installed your application in their store. It doesn’t expire, so it is available to you at all times. You will only need to get a new access token in case a user uninstalls the application from their store and installs your application back again.

With private access token you can use any method within the access scope range that you requested from an Ecwid user on initial steps of oAuth process.

After the moment user installs your app, it can store that token securely in your database for that user. So it’s not necessary to go through the standard oAuth flow each time you need to make a request to Ecwid API.

Public access token

Public access token example

{
    "public_token": "public_asdkjlsaASKDjaslkdASmndcasmrdgaSj"
}

Public token provides limited access to public store data via REST API interface. While private tokens allow you to modify something in a store, like update an order status or change storkc levels, public tokens can only get limited information from a store and create orders with limitations.

With public access token you can use these methods from anywhere (client-side JavaScript, widget integration codes, etc.):

These methods are available for public token regardless of the other access scope your requested from a store.

Native applications

Get access token in native apps

var storeData = EcwidApp.getPayload();

var storeId = storeData.store_id;
var accessToken = storeData.access_token;

// Use accessToken and storeId variables to make requests to Ecwid REST API
// ...

Check native apps guideline for general guides

https://developers.ecwid.com/native-applications

Native applications work in a separate tab in Ecwid Control Panel. After user installs an application, Ecwid will redirect user to the new tab. In that tab, your application can interact with the store on behalf of the user.

To get access token and start making requests to Ecwid API, use Ecwid JS SDK and a couple of Javascript lines of code - see example on the right.

See native apps documentation and start working on your application.

External applications

External applications work outside of Ecwid control panel and they also have an app details page for easy installation process. These apps use oAuth2 flow to get access token for a specific Ecwid store.

Check external apps guideline for general guides

https://developers.ecwid.com/external-applications

The installation process starts with user visiting app details page. On that page, they can install the app by providing the necessary permissions to it. Once the user clicks the “Install” button, Ecwid sends a user to your app’s Return URL along with the temporary code in the URL parameters.

Mind that in this case the installation process starts on Ecwid side and it might be the first time they open your site. Make sure your page on the return URL onboards users well – this is a landing page for them in your service. We recommend prefilling user details like: Name, email, Store name, Store ID and other fields that your service needs.

See External applications guideline for more information.

Get access token

Retrieving an access token for external apps includes the following steps:

  1. User installs application, Ecwid redirects the user to the return URL.
  2. Your code requests an access token from Ecwid in the background. This access_token will be used as API key in all API calls.

User will get to the first step by accessing your App details page in the Ecwid App Market. It is a separate page dedicated to describe your application in Ecwid Control Panel. Before you proceed, make sure you have a registered app to install and the application is registered for the Ecwid App Market.

Step 1. Ecwid redirects the user to a return URL of your app

Step #1: Return URL example

# Successfull authorization
https://www.example.com/myapp?code=1234567890

Upon successful installation, Ecwid redirects the user to the application’s redirect_uri with a code parameter in the URL. The value of this parameter is not an actual token for the store and it must be exchanged for the token in the next step of the process.

Return URL parameters

ParameterDescription
codeIf the user successfully authorizes the application, the query will contain the code parameter. That is a temporary code that your app should exchange to an access token. This code can be used only once and ‘lives’ for a few minutes so your app should request the token as soon as it gets the code. See step #2 for the details.
errorIf the user does not allow authorization to the application, query parameters indicate the user canceled authorization in error field

Step 2. Retrieve access_token from Ecwid in background

Step #2: Request example

https://my.ecwid.com/api/oauth/token?client_id=abcd0123&client_secret=01234567890abcdefg&code=987654321hgfdsa&redirect_uri=https%3A%2F%2Fwww%2Eexample%2Ecom%2Fmyapp&grant_type=authorization_code

POST https://my.ecwid.com/api/oauth/token?client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}&grant_type=authorization_code

ParameterRequiredDescription
client_idrequiredApplication ID
client_secretrequiredApplication secret key
coderequiredThe temporary code received on the step #1
redirect_urirequiredRedirect URL of your application
grant_typerequiredMust be authorization_code

Step #2: Response example

{
 "access_token":"secure_123453lasdADSKasasdjasdklasASkmns",
 "token_type":"bearer",
 "scope":"read_store_profile update_catalog",
 "store_id":1003,
 "public_token":"public_qKDUqKkNXzcj9DejkMUqEkYLq2E6BXM9"
}

Ecwid responds with a JSON-formatted data containing the access token and additional information. The response fields are listed below:

FieldDescription
access_tokenPrivate authorization token. This is a key your app will use to access Ecwid API on behalf of the user.
token_type bearer (it’s always bearer)
scopeList of permissions (API access scopes) given to the app, separated by space
store_idEcwid store ID (a unique Ecwid account identificator)
public_token Public authorization token. Provided if requested access scopes contain public_storefront scope.

Access scopes

Scopes are permissions that identifies the scope of access your application requests from the user. Below you can see the names of access scopes that exist in Ecwid API and their description.

Each application has their specified set of access scopes which are required for this applicaiton. If you specify additional scopes, that excess the specified ones for the app in Ecwid, you will see an error message. So if you need to add more access scopes - please contact us to update your app.

Access scopeNotes
read_store_profileGet store name and general settings, get store admin email, get updates statistics etc. Requested in all cases even if not specified
update_store_profileSet taxes, update invoice logo, change Starter Site domain, close store for maintenance etc.
read_catalogSearch products, get product options/combinations etc. Also allows to receive push updates (webhooks) about changes in store products.
update_catalogUpdate product prices, upload images and e-goods, modify product attributes etc.
create_catalogCreate new products
read_ordersGet sales for a given period, retrieve order details etc. Also allows to receive push updates (webhooks) about changes in store orders.
update_ordersChange order totals, switch order status, cancel orders etc.
create_ordersPlace a new order in the store
read_customersSearch customers or retrieve some particular customer data
update_customersChange customer profile data, add items to the customer address book etc.
create_customersAdd a new customer to the store’s Customers list
read_discount_couponsGet the list of discount coupons or retrieve some particular coupon details
update_discount_couponsChange the coupon expiration date or limit its number of use, update coupon code etc.
create_discount_couponsAdd a new discount coupon
customize_storefrontAttach a custom JS/CSS to the storefront on the fly to modify its look and feel (see Customizing storefront)
add_to_cpAdd a new tab to merchant control panel (see Embedding apps)
add_shipping_methodAdd a new shipping method to the store (see Custom Shipping API)
add_payment_methodAdd a new payment method to the store (see Add Payment Method)
read_storesCheck if there is a store already registered with an email (see Manage Stores)
create_storesCreate a new Ecwid store using API (see Manage Stores)
public_storefrontGet public store details with public access token
customize_cart_calculationApply custom discounts to orders in real time

Complete oAuth flow

This method of getting access token is meant for apps that are installed outside of the Ecwid App Market, for example: apps that work on a device, apps for mobile devices, CMS plugins, etc.

These kinds of apps can be also displayed in the Ecwid App Market, but the oAuth flow will be performed on an external website, where developer will decide how to handle the installation.

We recommend using the simplified installation flow from the Get access token section, however if it’s not possible or the application is created for a specific Ecwid store only, you can use this complete oAuth flow. Before you proceed, make sure you have a registered app to install.

Retrieving an access token in a complete oAuth flow includes the following steps:

  1. You send the user to Ecwid authorization dialog available on the Ecwid’s oAuth endpoint.
  2. Upon authorization, Ecwid redirects the user to the return URL specified in the request.
  3. The your code requests an access token from Ecwid. This access_token will be used as API key in all API calls.

Step 1. Send user to Ecwid authorization dialog

Your application sends the user to Ecwid authorization dialog available on the Ecwid’s oAuth endpoint.

Step #1: Request example

https://my.ecwid.com/api/oauth/authorize?client_id=abcd0123&redirect_uri=https%3A%2F%2Fwww%2Eexample%2Ecom%2Fmyapp&response_type=code&scope=read_store_profile+read_catalog+update_catalog+read_orders

GET https://my.ecwid.com/api/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}

ParameterRequiredDescription
client_idrequiredApplication ID
redirect_urirequiredURI in your app where users will be sent after authorization. It must match the domain/URL of the registered return_url specified in the app settings. I.e. if the registered return_url is http://www.example.com, the redirect_uri in request might be http://www.example.com/oauth/callback.php , but not http://www.example2.com/
response_typerequired code (must always be code)
scoperequiredScope of access that your app requests from the user, separated by space. See all possible values in Scopes section

Step 2. Ecwid redirects the user back to a return URL

Step #2: Return URLs example

# Successfull authorization
https://www.example.com/myapp?code=1234567890

# The user denied to provide access
https://www.example.com/myapp?error=access_denied

Upon authorization, Ecwid redirects the user to the application’s redirect_uri specified in request with a code parameter in that URL. The value of this parameter is not an actual token for the store and it must be exchanged for the token in the next step of the process.

Return URL parameters

ParameterDescription
codeIf the user successfully authorizes the application, the query will contain the code parameter. That is a temporary code that your app should exchange to an access token. This code can be used only once and lives for a few minutes so your app should request the token as soon as it gets the code. See the Authorization step #3 for the details.
errorIf the user does not allow authorization to the application, query parameters indicate the user canceled authorization in error field

Step 3. Retrieve access_token from Ecwid in background

Step #3: Request example

https://my.ecwid.com/api/oauth/token?client_id=abcd0123&client_secret=01234567890abcdefg&code=987654321hgfdsa&redirect_uri=https%3A%2F%2Fwww%2Eexample%2Ecom%2Fmyapp&grant_type=authorization_code

POST https://my.ecwid.com/api/oauth/token?client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}&grant_type=authorization_code

ParameterRequiredDescription
client_idrequiredApplication ID
client_secretrequiredApplication secret key
coderequiredThe temporary code received on the step #2
redirect_uriconditionalIf the redirect_uri parameter was included in the authorization request, you must include it in the token request and their values must be identical.
grant_typerequiredMust be authorization_code

Step #3: Response example

{
 "access_token":"12345",
 "token_type":"bearer",
 "scope":"read_store_profile update_catalog",
 "store_id":1003,
 "public_token":"public_qKDUqKkNXzcj9DejkMUqEkYLq2E6BXM9"
}

Ecwid responds with a JSON-formatted data containing the access token and additional information. The response fields are listed below:

FieldDescription
access_tokenPrivate authorization token. This is a key your app will use to access Ecwid API on behalf of the user.
token_type bearer (it’s always bearer)
scopeList of permissions (API access levels) given to the app, separated by space
store_idEcwid store ID (a unique Ecwid account identificator)
public_token Public authorization token. Provided if requested access scopes contain public_storefront scope.

Q: What if my app always redirects users to different domain?

Some applications requires user to download and install them on their site rather than providing a hosted solution. For example, plugins for Wordpress, Joomla or other CMS systems do that. Every instance of such application resides on different domain and thus has different Return URL.

To implement oAuth flow in such an app, you will need enable support for multiple domains in redirect_uri and improve security: application will always ask user for permissions and will show the domain that requests them in the oAuth flow. Contact us if your application is of this kind and we will make the necessary changes.

Applications installed on device

In case of applications that are installed on a device (such as a computer, a cell phone, or a tablet), the application client_secret is in general less protected than in case of web services. Thus the process of retrieving access token is changed as described below.

Changes in Step #1

Step #1: Request example

https://my.ecwid.com/api/oauth/authorize?client_id=abcd0123&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=read_store_profile+read_catalog+update_catalog+read_orders

On the Step #1 (app requests a temporarily authorization code), application needs to send the following value as redirect_uri:

urn:ietf:wg:oauth:2.0:oob

The rest of request parameters are the same as for web services.

Changes in Step #2

Step #2: User grants permission

<title>oauth_response:code=54xgQHmbZrrLTqzCiHPyw&amp;state=code</title>

Step #2. User denies to provide the app with access

<title>oauth_response:error=access_denied</title>

On the Step #2 (Ecwid provides the app with a temporary authorization code), Ecwid will not direct a user to redirect_uri after the user agrees or disagrees to provide the application with permissions. Instead, Ecwid opens an empty page and provides the code in the page’s <title> tag. I.e., all the data is sent to application in the page title tag and no data is sent in GET request to the application. The format of data provided in the <title> tag is the following:

oauth_response:GET-query-as-it-would-be-transferred-via-redirect

Changes in Step #3

The Step #3 (the app exchanges the temporarily authorization code to an access token) is not changed. Everything works the same way for installed apps as it does for web apps.

App details page

To install any application from the Ecwid App Market, user would need to visit an app details page for that application first. Typical app details link in Ecwid Control Panel looks like this:

https://my.ecwid.com/cp/CP.html#apps:view=app&name=my-cool-app

Where my-cool-app is the appId provided to you when you registered your application with us. App details page contains various information like app description, screenshots, pricing and other details.

Public app details page of Ecwid app for iOS

https://www.ecwid.com/apps/storemanagement/ecwid-iphone-app

User can install the application into their Ecwid store from this page and this process replaces the oAuth dialog, because user is already in the Ecwid Control Panel. After that, your app will request store permissions that you specified when you registered the application and proceed according to the type of the application (see below).

To set up an app details page for your public application, see Publishing Your App page for details.

The app installation works different for different app types:

  • Ecwid will redirect user to app tab in Ecwid Control Panel if it’s a Native app
  • Ecwid will redirect user to external website with temporary code if it’s an External app
  • Ecwid will not redirect user anywhere if no redirect is specified for the app

REST API Reference

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

UTC

Date/time values returned by Ecwid API are in UTC.

API Version

This document describes Ecwid REST API v.3

API calls limits

You are free to build your app with as many API calls as you need to make your service awesome for Ecwid merchants, but keep in mind the usage policy.

Usage policy

By default, we do not limit API usage for applications. You are free to build your app with as many calls as you need to make your service awesome for Ecwid merchants.

However, to protect us and our users from abusing, we ask you to 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

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 attempt to get in touch with the developer to talk about the 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.

Q: How can I make the 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:

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 section for more details.

Here are some resources we can recommend to get started:

For testing out the API functionality we can also recommend using Ecwid API Playground.

Store information

Get store profile

Request example

GET /api/v3/4870020/profile?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/profile?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Response

Response example (JSON)

{
    "generalInfo": {
        "storeId": 4870020,
        "storeUrl": "http://www.example.com",
        "starterSite": {
            "ecwidSubdomain": "mysuperstore",
            "generatedUrl": "http://mysuperstore.ecwid.com/"
        }
    },
    "account": {
        "accountName": "John Smith",
        "accountNickName": "JSmith",
        "accountEmail": "example@example.com"
    },
    "settings": {
        "closed": false,
        "storeName": "My Super Store",
        "invoiceLogoUrl": "https://dpbfm6h358sh7.cloudfront.net/images/4870020/253584290.jpg",
        "emailLogoUrl": "https://dpbfm6h358sh7.cloudfront.net/images/4870020/298177033.jpg",
        "googleRemarketingEnabled": true,
        "googleAnalyticsId": "UA-123456-1",
        "orderCommentsEnabled": false,
        "orderCommentsCaption": "Order comments",
        "orderCommentsRequired": false,
        "hideOutOfStockProductsInStorefront": true
    },
    "mailNotifications": {
        "adminNotificationEmails": [
            "john@example.com",
            "steve@example.com",
        ],
        "customerNotificationFromEmail": "john@example.com"
    },
    "company": {
        "companyName": "My Super Store",
        "email": "example@example.com",
        "street": "W 3d st",
        "city": "New York",
        "countryCode": "US",
        "postalCode": "10001",
        "stateOrProvinceCode": "NY",
        "phone": "234324234"
    },
    "formatsAndUnits": {
        "currency": "USD",
        "currencyPrefix": "$",
        "currencySuffix": "",
        "currencyGroupSeparator": " ",
        "currencyDecimalSeparator": ".",
        "currencyTruncateZeroFractional": false,
        "currencyPrecision": 2,
        "currencyRate": 1,
        "weightUnit": "KILOGRAM",
        "weightGroupSeparator": " ",
        "weightDecimalSeparator": ".",
        "weightTruncateZeroFractional": false,
        "timeFormat": "hh:mm a",
        "dateFormat": "MMM d, yyyy",
        "timezone": "Europe/Moscow",
        "dimensionsUnit": "CM",
        "orderNumberPrefix": "00001",
        "orderNumberSuffix": "5000"
    },
    "languages": {
        "enabledLanguages": [
            "en",
            "es",
            "pt"
        ],
        "facebookPreferredLocale": "en_US"
    },
    "shipping": {
        "handlingFee": {
            "name": "Handling Fee",
            "value": 5,
            "description": "Silk paper wrapping"
        }
    },
    "zones": [
        {
            "id": "1",
            "name": "United States",
            "countryCodes": [
                "US",
                "UM",
                "VI"
            ]
        },
        {
            "id": "2",
            "name": "US & Canada",
            "countryCodes": [
                "CA",
                "US",
                "UM",
                "VI"
            ]
        },
        {
            "id": "3",
            "name": "Europe (EC)",
            "countryCodes": [
                "AT",
                "BE",
                "BG",
                "CY",
                "CZ",
                "DK",
                "EE",
                "FI",
                "FR",
                "DE",
                "GR",
                "HU",
                "IE",
                "IT",
                "LV",
                "LT",
                "LU",
                "MT",
                "NL",
                "PL",
                "PT",
                "RO",
                "SK",
                "SI",
                "ES",
                "SE",
                "GB"
            ]
        },
    ],
    "taxSettings": {
        "automaticTaxEnabled": true,
        "taxes": [
            {
                "id": 1485869949,
                "name": "Tax X",
                "enabled": true,
                "includeInPrice": false,
                "useShippingAddress": true,
                "taxShipping": false,
                "appliedByDefault": true,
                "defaultTax": 7,
                "rules": [
                    {
                        "zoneId": "3",
                        "tax": 8
                    },
                    {
                        "zoneId": "2",
                        "tax": 5
                    }
                ]
            }
        ]
    },
    "businessRegistrationID": {
        "name": "VAT Reg No",
        "value": "GB999 9999 73"
    }
}

Public token request example

GET /api/v3/4870020/profile?token=public_123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache
{
  "generalInfo": {
    "storeId": 5035009,
    "storeUrl": "https://example.com",
    "starterSite": {
      "ecwidSubdomain": "demo",
      "generatedUrl": "https://demo.ecwid.com"
    }
  },
  "settings": {
    "closed": false,
    "storeName": "Awesome store",
    "googleAnalyticsId": ""
  },
  "mailNotifications": {
    "customerNotificationFromEmail": "info@example.com"
  },
  "company": {
    "companyName": "Cool slippers for dogs",
    "email": "info@example.com",
    "street": "W 3d st",
    "city": "New York",
    "countryCode": "US",
    "postalCode": "10002",
    "stateOrProvinceCode": "NY",
    "phone": ""
  },
  "formatsAndUnits": {
    "currency": "USD",
    "currencyPrefix": "$",
    "currencySuffix": "",
    "currencyGroupSeparator": " ",
    "currencyDecimalSeparator": ".",
    "currencyPrecision": 2,
    "currencyTruncateZeroFractional": false,
    "currencyRate": 1,
    "weightUnit": "KILOGRAM",
    "weightGroupSeparator": " ",
    "weightDecimalSeparator": ".",
    "weightTruncateZeroFractional": false,
    "timeFormat": "hh:mm a",
    "dateFormat": "EEE, MMM d, ''yy",
    "timezone": "Europe/Samara",
    "dimensionsUnit": "CM"
  },
  "languages": {
    "enabledLanguages": [
      "en",
      "ar",
      "be",
      "bg",
      "ca",
      "cs",
      "cy",
      "da",
      "de",
      "el",
      "es",
      "es_419",
      "et",
      "eu",
      "fi",
      "fa",
      "fr",
      "id",
      "is",
      "it",
      "ja",
      "he",
      "hr",
      "hu",
      "hy",
      "ka",
      "ko",
      "lt",
      "lv",
      "mk",
      "mr",
      "ms",
      "nl",
      "no",
      "pl",
      "pt",
      "pt_BR",
      "ro",
      "ru",
      "sk",
      "sl",
      "sr",
      "sv",
      "sq",
      "th",
      "tr",
      "uk",
      "vi",
      "zh",
      "zh_TW"
    ],
    "facebookPreferredLocale": "en_US"
  }
}

A JSON object of type ‘Profile’ with the following fields:

Profile

FieldTypeDescription
generalInfo<GeneralInfo>Store basic data
account<Account>Store owner’s account data
settings<Settings>Store general settings
mailNotifications<MailNotifications>Mail notifications settings
company<Company>Company info
formatsAndUnits<FormatsAndUnits>Store formats/untis settings
languages<Languages>Store language settings
shipping<Shipping>Store shipping settings (only handling fee is included at the moment)
taxSettings<TaxSettings>Store taxes settings
zonesArray<Zone>Store destination zones
businessRegistrationID<BusinessRegistrationID>Company registration ID, e.g. VAT reg number or company ID, which is set under Settings / Invoice in Control panel.

GeneralInfo

FieldTypeDescription
storeIdnumberEcwid Store ID
storeUrlstringStorefront URL
starterSite<StarterSiteInfo>Starter Site settings

Account

FieldTypeDescription
accountNamestringFull store owner name
accountNickNamestringStore owner nickname on the Ecwid forums
accountEmailstringStore owner email
availableFeaturesArray<string>A list of the premium features available on the store’s pricing plan

Settings

FieldTypeDescription
closedboolean true if the store is closed for maintenance, false otherwise
storeNamestringThe store name displayed in Starter Site
invoiceLogoUrlstringCompany logo displayed on the invoice
emailLogoUrlstringCompany logo displayed in the store email notifications
googleRemarketingEnabledboolean true if Remarketing with Google Analytics is enabled, false otherwise
googleAnalyticsIdstring Google Analytics ID connected to a store
orderCommentsEnabledboolean true if order comments feature is enabled, false otherwise
orderCommentsCaptionstringCaption for order comments field in storefront
orderCommentsRequiredboolean true if order comments are required to be filled, false otherwise
hideOutOfStockProductsInStorefrontboolean true if out of stock products are hidden in storefront, false otherwise. This setting is located in Ecwid Control Panel > Settings > General > Cart

MailNotifications

FieldTypeDescription
adminNotificationEmailsArray<string>Email addresses, which the store admin notifications are sent to
customerNotificationFromEmailstringThe email address used as the 'reply-to’ field in the notifications to customers

Company

System Settings → General → Store Profile

FieldTypeDescription
companyNamestringThe company name displayed on the invoice
emailstringCompany (store administrator) email
streetstringCompany address. 1 or 2 lines separated by a new line character
citystringCompany city
countryCodestringA two-letter ISO code of the country
postalCodestringPostal code or ZIP code
stateOrProvinceCodestringState code (e.g. NY) or a region name
phonestringCompany phone number

FormatsAndUnits

System settings → General → Formats & Units.

FieldTypeDescription
currencystring3-letters code of the store currency (ISO 4217). Examples: USD, CAD
currencyPrefixstringCurrency prefix (e.g. $)
currencySuffixstringCurrency suffix
currencyPrecisionnumberNumbers of digits after decimal point in the store prices. E.g. 2 ($2.99) or 0 (¥500).
currencyGroupSeparatorstringPrice thousands separator. Supported values: space , dot ., comma , or empty value “.
currencyDecimalSeparatorstringPrice decimal separator. Possible values: . or ,
currencyTruncateZeroFractionalbooleanHide zero fractional part of the prices in storefront. true or false .
currencyRatenumberCurrency rate in U.S. dollars, as set in the merchant control panel
weightUnitstringWeight unit. Supported values: CARAT, GRAM, OUNCE, POUND, KILOGRAM
weightPrecisionnumberNumbers of digits after decimal point in weights displayed in the store
weightGroupSeparatorstringWeight thousands separator. Supported values: space , dot ., comma , or empty value ”
weightDecimalSeparatorstringWeight decimal separator. Possible values: . or ,
weightTruncateZeroFractionalbooleanHide zero fractional part of the weight values in storefront. true or false .
dateFormatstringDate format, e.g. MMM d, yyyy
timeFormatstringTime format, e.g. hh:mm a
timezonestringStore timezone, e.g. Europe/Moscow
dimensionsUnitstringProduct dimensions units
orderNumberPrefixstringOrder number prefix in a store
orderNumberSuffixstringOrder number suffix in a store

Languages

System Settings → General → Languages

FieldTypeDescription
enabledLanguagesArray<string>A list of enabled languages in the storefront. First language code is the default language for the store.
facebookPreferredLocalestringLanguage automatically chosen be default in Facebook storefront (if any)

Shipping

System Settings → Shipping

FieldTypeDescription
handlingFee<HandlingFee>Handling fee settings

HandlingFee

System Settings → Shipping → Handling Fee

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHndling fee value
descriptionstringHandling fee description for customer

TaxSettings

System Settings → Taxes

FieldTypeDescription
automaticTaxEnabledboolean true if taxes are calculated automatically, else otherwise
taxesArray<Taxes>Manual tax settings for a store

Taxes

FieldTypeDescription
idnumberUnique internal ID of the tax
namestringDisplayed tax name
enabledbooleanWhether tax is enabled true / false
includeInPriceboolean true if the tax rate is included in product prices. More details: Taxes in Ecwid
useShippingAddressboolean true if the tax is calculated based on shipping address, false if billing address is used
taxShippingboolean true is the tax applies to subtotal+shipping cost . false if the tax is applied to subtotal only
appliedByDefaultboolean true if the tax is applied to all products. false is the tax is only applied to thos product that have this tax enabled
defaultTaxnumberTax value, in %, when none of the destination zones match
rulesArray<TaxRule>Tax rates

TaxRule

FieldTypeDescription
zoneIdstringDestination zone ID
taxnumberTax rate for this zone in %

Zone

System Settings → Zones

FieldTypeDescription
idstringUnique internal zone ID
namestringZone displayed name
countryCodesArray<string>Country codes this zone includes .
stateOrProvinceCodesArray<string>State or province codes the zone includes
postCodesArray<string>Postcode (or zipcode) templates this zone includes. More details: Destination zones in Ecwid

BusinessRegistrationID

FieldTypeDescription
namestringID name, e.g. Vat ID, P.IVA, ABN
valuestringID value

StarterSiteInfo

System Settings → General → Starter site

FieldTypeDescription
ecwidSubdomainstringStore subdomain on ecwid.com domain, e.g. mysuperstore.ecwid.com
customDomainstringCustom Starter site domain, e.g. www.mysuperstore.com
generatedUrlstringStarter Site generated URL, e.g. http://mysuperstore.ecwid.com/
storeLogoUrlstringStarter Site logo URL

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the coupon info because of an error on the server

Update store profile

Request example – update general info

PUT /api/v3/4870020/profile?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

{
    generalInfo: {
        storeUrl: "http://www.example.com/store/"
    },
    settings: {
        closed: false,
        storeName: "My Cool Store",
        "googleRemarketingEnabled": false,
        "googleAnalyticsId": "UA-654321-1",
        "hideOutOfStockProductsInStorefront": false
    },
    company: {
      companyName: "My Company, Inc",
      email: "store@example.com",
      street: "144 West D Street",
      city: "Encinitas",
      countryCode: "US",
      postalCode: "92024",
      stateOrProvinceCode: "CA",
      phone: "1(800)5555555"
    }
}

Request example – create destination zones

PUT /api/v3/4870020/profile?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

{
    "zones": [
        {
            "name": "United States - California",
            "countryCodes": [
                "US"
            ],
            "stateOrProvinceCodes": [
                "US-CA"
            ]      
        }
    ]
}

PUT https://app.ecwid.com/api/v3/{storeId}/profile?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'Profile’ with the following fields:

Profile

FieldTypeDescription
generalInfo<GeneralInfo>Store basic data
account<Account>Store owner’s account data
settings<Settings>Store general settings
mailNotifications<MailNotifications>Mail notifications settings
company<Company>Company info
formatsAndUnits<FormatsAndUnits>Store formats/untis settings
languages<Languages>Store language settings
shipping<Shipping>Store shipping settings (only handling fee is included at the moment)
taxSettings<TaxSettings>Store taxes settings
zonesArray<Zone>Store destination zones
businessRegistrationID<BusinessRegistrationID>Company registration ID, e.g. VAT reg number or company ID, which is set under Settings / Invoice in Control panel.

GeneralInfo

FieldTypeDescription
storeUrlstringStorefront URL. If this field is empty in the store settings and omitted in the request, it will be automatically copied from the current Starter Site URL. When updating, make sure to add protocol to the URL (http:// or https://).
starterSite<StarterSiteInfo>Starter Site settings

Account

FieldTypeDescription
accountNamestringFull store owner name
accountNickNamestringStore owner nickname on the Ecwid forums
accountEmailstringStore owner email

Settings

FieldTypeDescription
closedstring true if the store is closed for maintenance, false otherwise
storeNamestringThe store name displayed in Starter Site
googleRemarketingEnabledboolean true if Remarketing with Google Analytics is enabled, false otherwise
googleAnalyticsIdstring Google Analytics ID connected to a store
orderCommentsEnabledbooleanUse true to enable order comments feature, false otherwise
orderCommentsCaptionstringCaption for order comments field in storefront. If the value is empty, the default 'Order comments’ caption will be used
orderCommentsRequiredbooleanUse true to require order comments to be filled, false otherwise
hideOutOfStockProductsInStorefrontboolean true if out of stock products are hidden in storefront, false otherwise. This setting is located in Ecwid Control Panel > Settings > General > Cart

MailNotifications

FieldTypeDescription
adminNotificationEmailsArray<string>Email addresses, which the store admin notifications are sent to
customerNotificationFromEmailstringThe email address used as the 'reply-to’ field in the notifications to customers

Company

System Settings → General → Store Profile

FieldTypeDescription
companyNamestringThe company name displayed on the invoice
emailstringCompany (store administrator) email
streetstringCompany address. 1 or 2 lines separated by a new line character
citystringCompany city
countryCodestringA two-letter ISO code of the country
postalCodestringPostal code or ZIP code
stateOrProvinceCodestringState code (e.g. NY) or a region name
phonestringCompany phone number

FormatsAndUnits

System settings → General → Formats & Units.

FieldTypeDescription
currencystring3-letters code of the store currency (ISO 4217). Examples: USD, CAD
currencyPrefixstringCurrency prefix (e.g. $)
currencySuffixstringCurrency suffix
currencyGroupSeparatorstringPrice thousands separator. Supported values: space , dot ., comma , or empty value “.
currencyDecimalSeparatorstringPrice decimal separator. Possible values: . or ,
currencyTruncateZeroFractionalbooleanHide zero fractional part of the prices in storefront. true or false .
currencyRatenumberCurrency rate in U.S. dollars, as set in the merchant control panel
weightUnitstringWeight unit. Supported values: CARAT, GRAM, OUNCE, POUND, KILOGRAM
weightPrecisionnumberNumbers of digits after decimal point in weights displayed in the store
weightGroupSeparatorstringWeight thousands separator. Supported values: space , dot ., comma , or empty value ”
weightDecimalSeparatorstringWeight decimal separator. Possible values: . or ,
weightTruncateZeroFractionalbooleanHide zero fractional part of the weight values in storefront. true or false .
dateFormatstringDate format, e.g. MMM d, yyyy
timeFormatstringTime format, e.g. hh:mm a
timezonestringStore timezone, e.g. Europe/Moscow
dimensionsUnitstringProduct dimensions units. Possible values: IN,CM,MM,YD
orderNumberPrefixstringOrder number prefix in a store
orderNumberSuffixstringOrder number suffix in a store

Languages

System Settings → General → Languages

FieldTypeDescription
enabledLanguagesArray<string>A list of enabled languages in the storefront. Use first item to set default storefront language

Shipping

System Settings → Shipping

FieldTypeDescription
handlingFee<HandlingFee>Handling fee settings

HandlingFee

System Settings → Shipping → Handling Fee

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value. If handling fee is 0 then it’s disabled.
descriptionstringHandling fee description for customer

TaxSettings

System Settings → Taxes

FieldTypeDescription
automaticTaxEnabledboolean true if taxes are calculated automatically, else otherwise
taxesArray<Taxes>Manual tax settings for a store

Taxes

FieldTypeDescription
idnumberUnique internal ID of the tax
namestringDisplayed tax name
enabledbooleanWhether tax is enabled true / false
includeInPriceboolean true if the tax rate is included in product prices. More details: Taxes in Ecwid
useShippingAddressboolean true if the tax is calculated based on shipping address, false if billing address is used
taxShippingboolean true is the tax applies to subtotal+shipping cost . false if the tax is applied to subtotal only
appliedByDefaultboolean true if the tax is applied to all products. false is the tax is only applied to thos product that have this tax enabled
defaultTaxnumberTax value, in %, when none of the destination zones match
rulesArray<TaxRule>Tax rates

TaxRule

FieldTypeDescription
zoneIdstringDestination zone ID
taxnumberTax rate for this zone in %

Zone

System Settings → Zones

FieldTypeDescription
idstringUnique internal zone ID
namestringZone displayed name
countryCodesArray<string>Country codes this zone includes
stateOrProvinceCodesArray<string>State or province codes the zone includes
postCodesArray<string>Postcode (or zipcode) templates this zone includes. More details: Destination zones in Ecwid

BusinessRegistrationID

FieldTypeDescription
namestringID name, e.g. Vat ID, P.IVA, ABN
valuestringID value

StarterSiteInfo

System Settings → General → Starter site

FieldTypeDescription
ecwidSubdomainstringStore subdomain on ecwid.com domain, e.g. mysuperstore.ecwid.com
customDomainstringCustom Starter site domain, e.g. www.mysuperstore.com

Response

Response example (JSON)

{
    "updateCount": 1,
    "success": true
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated entities (1 or 0 depending on whether the update was successful)
successboolean true if the coupon has been updated, false otherwise

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402Cannot update settings because the limit of number of zones or taxes is reached
409Cannot update profile because such nickname or email is already registered in the system
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the coupon info because of an error on the server

Upload store logo displayed on Starter Site. The logo itself is to be placed in the request body. Maximum allowed file size is 20Mb.

Request example

POST /api/v3/4870020/profile/logo?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/profile/logo?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/profile/logo?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/profile/logo?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

When uploading a store logo, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
    "id": 240198557
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal image ID

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
413The image file is too large (Maximum allowed file size is 20Mb)
415Unsupported content-type: expected application/octet-stream
422The uploaded file is not an image
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Remove store logo, which is displayed on Starter site

Request example

DELETE /api/v3/4870020/profile/logo?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json

DELETE https://app.ecwid.com/api/v3/{storeId}/profile/logo?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1,
    "success": true
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted images (1 or 0 depending on whether the request was successful)
successboolean true if the image has been deleted, false otherwise

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload store logo displayed on order invoices. The logo itself is to be placed in the request body. Maximum allowed file size is 20Mb.

Request example

POST /api/v3/4870020/profile/invoicelogo?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/profile/invoicelogo?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/profile/invoicelogo?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/profile/invoicelogo?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

When uploading an invoice logo, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
    "id": 240198557
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal image ID

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
415Unsupported content-type: expected application/octet-stream
422The uploaded file is not an image
413The image file is too large. Maximum allowed file size is 20Mb.
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Remove store logo, which is displayed on order invoices

Request example

DELETE /api/v3/4870020/profile/invoicelogo?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json

DELETE https://app.ecwid.com/api/v3/{storeId}/profile/invoicelogo?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1,
    "success": true
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted images (1 or 0 depending on whether the request was successful)
successboolean true if the image has been deleted, false otherwise

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get store update statistics

This method provides simple 'Latest updates’ statistics about store profile, products, orders, categories and discount coupons. Use it to check whether something was changed in an Ecwid store. This could be helpful to keep data in your application up-to-date and avoid abusing API to get and parse large amounts of data to check its state.

Also, you can consider using webhooks to get a notificaiton when changes are made to orders and catalog items. For example, you can get a webhook when a new order is placed in a store and send order details to a warehouse right away.

Request example

GET /api/v3/4870020/latest-stats?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/latest-stats?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Response

Response example (JSON)

{
    "productsUpdated": "2014-10-19 18:56:21 +0400",
    "ordersUpdated": "2014-10-15 16:54:11 +0400",
    "profileUpdated": "2014-10-19 18:55:35 +0400",
    "categoriesUpdated": "2014-10-19 12:23:12 +0400",
    "discountCouponsUpdated": "2017-02-10 08:03:43 +0000"
}

A JSON object containing the update dates statistics

UpdateStats

FieldTypeDescription
productsUpdatedstringDate of the latest changes in store catalog (products, categories), e.g. 2014-10-15 16:54:11 +0400
ordersUpdatedstringDate of the latest changes in store orders, e.g. 2014-10-15 16:54:11 +0400
profileUpdatedstringDate of the latest changes in store information, e.g. 2014-10-15 16:54:11 +0400
categoriesUpdatedstringDate of the latest changes in store categories, e.g. 2014-10-19 12:23:12 +0400
discountCouponsUpdatedstringDate of the latest changes in store discount coupons, e.g. 2014-10-19 12:23:12 +0400

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500There was an internal server error while processing the request

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get deleted items statistics

Using this group of API methods, you can get a list of products, orders, customers and coupons that have been deleted from the store. In combination with the update statistics, you can use these endpoints to check whether something was changed in an Ecwid store and keep data in your application synchronized with the Ecwid store you’re working with.

Also, you can consider using webhooks to get a notificaiton when orders and catalog items are deleted. For example, you can get a webhook right after a product is deleted from an Ecwid store and adjust your custom product list in external system.

Get deleted products stats

GET /api/v3/4870020/products/deleted?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

Get deleted orders stats

GET /api/v3/4870020/orders/deleted?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

Get deleted customers stats

GET /api/v3/4870020/customers/deleted?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

Get deleted coupons stats

GET /api/v3/4870020/discount_coupons/deleted?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

There are 4 endpoints: deleted products, orders, customers, coupons.

  • GET https://app.ecwid.com/api/v3/{storeId}/products/deleted?from_date={from_date}&to_date={to_date}&offset={offset}&limit={limit}&token={token}
  • GET https://app.ecwid.com/api/v3/{storeId}/orders/deleted?from_date={from_date}&to_date={to_date}&offset={offset}&limit={limit}&token={token}
  • GET https://app.ecwid.com/api/v3/{storeId}/customers/deleted?from_date={from_date}&to_date={to_date}&offset={offset}&limit={limit}&token={token}
  • GET https://app.ecwid.com/api/v3/{storeId}/discount_coupons/deleted?from_date={from_date}&to_date={to_date}&offset={offset}&limit={limit}&token={token}
NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
from_datestringItem deletion date lower bound. Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
Examples:
  • 1447804800
  • 2015-04-22 18:48:38 -0500
  • 2015-04-22 (this is 2015-04-22 00:00:00 UTC)
to_datestringItem deletion date upper bound. Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Default value: 100

Response

Response example (JSON). Removed order stats

{
    "total": 1,
    "count": 1,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 9,
            "date": "2014-10-20 18:07:24 +0400"
        }
    ]
}

Response example (JSON). Removed coupons stats

{
    "total": 2,
    "count": 2,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 34256365236,
            "date": "2014-10-20 18:00:54 +0400"
        },
        {
            "id": 123123213213,
            "date": "2014-10-20 18:00:57 +0400"
        }
    ]
}

Each endpoint returns the information about the batch, the removed items IDs and the deletion dates in JSON object of type DeletedItemsStats

DeletedItemsStats

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe total number of the items returned in this batch
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
itemsArrayThe removed items list with IDs and dates

Removed item

FieldTypeDescription
idnumberItem ID. Depending on the request, that is products ID, customer ID, order number or coupon ID.
datestringItem deletion date

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500There was an internal server error while processing the request

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Products

Search products

Search/filter store products

Request

Request examples

GET /api/v3/4870020/products?limit=2&keyword=fruit&token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/products?keyword={keyword}&priceFrom={priceFrom}&priceTo={priceTo}&category={category}&withSubcategories={withSubcategories}&sortBy={sortBy}&offset={offset}&limit={limit}&createdFrom={createdFrom}&createdTo={createdTo}&updatedFrom={updatedFrom}&updatedTo={updatedTo}&enabled={enabled}&inStock={inStock}&field{attributeName}={attributeValues}&field{attributeId}={attributeValues}&sku={sku}&productId={productId}&baseUrl={baseUrl}&cleanUrls={cleanUrls}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
keywordstringSearch term. Use quotes to search for exact match. Ecwid searches products over multiple fields:
  • title
  • description
  • SKU
  • product options
  • category name
  • gallery image descriptions
  • attribute values (except for hidden attributes)
priceFromnumberMinimum product price
priceTonumberMaximum product price
categorynumberCategory ID
withSubcategoriesboolean true/false: defines whether Ecwid should search in subcategories of the category you set in category field. Ignored if category field is not set . false is the default value
sortBystringSort order. Supported values:
  • RELEVANCE default
  • ADDED_TIME_DESC
  • ADDED_TIME_ASC
  • NAME_ASC
  • NAME_DESC
  • PRICE_ASC
  • PRICE_DESC
  • UPDATED_TIME_ASC
  • UPDATED_TIME_DESC
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 100
createdFromstringProduct creation date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
Examples:
  • 1447804800
  • 2015-04-22 18:48:38 -0500
  • 2015-04-22 (this is 2015-04-22 00:00:00 UTC)
createdTostringProduct creation date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedFromstringProduct last update date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedTostringProduct last update date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
enabledboolean true to get only enabled products, false to get only disabled products
inStockboolean true to get only products in stock, false to get out of stock products
field{attributeName}stringFilter by product attribute values. Format: field{attributeName}=param[,param], where “attributeName” is the attribute name and “param” is the attribute value. You can place several values separated by comma. In that case values will be connected through logical “OR”, and if the product has at least one of them it will get to the search results. Example:
fieldBrand=Apple&fieldCapacity=32GB,64GB
field{attributeId}stringFilter by product attribute values. Works the same as the filter by field{attributeName} but attribute IDs are used instead of attribute names. This way is insensitive to attributes renaming.
skustringProduct or combination SKU. Ecwid will return details of a product containing that SKU, if SKU value is an exact match. If SKU is specified, other search parameters are ignored, except for product ID.
productIdnumberInternal Ecwid product ID or multiple productIds separated by a comma. If this field is specified, other search parameters are ignored.
baseUrlstringStorefront URL for Ecwid to use when returning product URLs in the url field. If not specified, Ecwid will use the storefront URL specified in the store settings
cleanUrlsbooleanIf true, Ecwid will return the SEO-friendly clean URL (without hash '#') in the url field. If false, Ecwid will return URL in the old format (with hash '#'). We recommend using true value if merchant’s website supports clean SEO-friendly URL feature

Response

Response example (JSON)

{
    "total": 5,
    "count": 2,
    "offset": 0,
    "limit": 2,
    "items": [
        {
          "id": 37208339,
          "sku": "00099",
          "thumbnailUrl": "http://app.ecwid.com/default-store/00011-232-sq.jpg",
          "quantity": 11,
          "unlimited": false,
          "inStock": true,
          "name": "Orange",
          "price": 10,
          "priceInProductList": 10,
          "wholesalePrices": [
            {
              "quantity": 2,
              "price": 9
            },
            {
              "quantity": 4,
              "price": 8
            }
          ],
          "compareToPrice": 23,
          "isShippingRequired": true,
          "weight": 0,
          "url": "http://app.ecwid.com#!/Orange/p/37208339",
          "created": "2015-10-05 07:26:14 +0000",
          "updated": "2016-02-03 10:01:02 +0000",
          "createTimestamp": 1444029974,
          "updateTimestamp": 1454493662,
          "productClassId": 0,
          "enabled": true,
          "options": [],
          "warningLimit": 0,
          "fixedShippingRateOnly": true,
          "fixedShippingRate": 0,
          "defaultCombinationId": 0,
          "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
          "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341234.jpg",
          "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341232.jpg",
          "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717703.jpg",
          "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124125.jpg",
          "originalImage": {
              "url": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124125.jpg",
              "width": 123,
              "height": 456
          },
          "description": "<p>It's a tasty fruit!</p>",
          "galleryImages": [
            {
              "id": 18481471,
              "alt": "AdditionalImage",
              "url": "https://dpbfm6h358sh7.cloudfront.net/images/5035009/312058848.jpg",
              "thumbnail": "https://dpbfm6h358sh7.cloudfront.net/images/5035009/351433814.jpg",
              "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690771.jpg",
              "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/1234123412312.jpg",
              "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341235.jpg",
              "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717705.jpg",
              "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124121.jpg",
              "width": 473,
              "height": 545,
              "orderBy": 0
            },
            {
              "id": 18481472,
              "alt": "AdditionalImage",
              "url": "https://dpbfm6h358sh7.cloudfront.net/images/5035009/312058850.jpg",
              "thumbnail": "https://dpbfm6h358sh7.cloudfront.net/images/5035009/351433815.jpg",
              "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
              "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/1234123412311.jpg",
              "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341238.jpg",
              "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/4617177879.jpg",
              "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124179.jpg",
              "width": 247,
              "height": 545,
              "orderBy": 1
            }
          ],
          "categoryIds": [
            19563207,
            19976005,
            19976006
          ],
          "categories": [
            {
              "id": 19976006,
              "enabled": true
            },
            {
              "id": 19976005,
              "enabled": true
            },
            {
              "id": 19563207,
              "enabled": false
            }
          ],
          "seoTitle": "Orange",
          "seoDescription": "It's a tasty orange for you and your family!",
          "defaultCategoryId": 0,
          "favorites": {
            "count": 0,
            "displayedCount": "0"
          },
          "attributes": [
            {
              "id": 8258226,
              "name": "Width",
              "value": "61.47 mm",
              "type": "CUSTOM",
              "show": "DESCR"
            },
            {
              "id": 8258231,
              "name": "Height",
              "value": "117.09 mm",
              "type": "CUSTOM",
              "show": "DESCR"
            },
            {
              "id": 8258249,
              "name": "Depth",
              "value": "15.49 mm",
              "type": "CUSTOM",
              "show": "DESCR"
            },
            {
              "id": 8258255,
              "name": "Net weight",
              "value": "153.2 g",
              "type": "CUSTOM",
              "show": "DESCR"
            }
          ],
          "files": [],
          "relatedProducts": {
            "productIds": [],
            "relatedCategory": {
              "enabled": false,
              "categoryId": 0,
              "productCount": 1
            }
          },
          "combinations": [],
          "dimensions": {
            "length": 0,
            "width": 0,
            "height": 0
          },
          "showOnFrontpage": 1
        },
        {
            "id": 37208340,
            "sku": "00007",
            "thumbnailUrl": "http://app.ecwid.com/default-store/00007-230-sq.jpg",
            "quantity": 67,
            "inStock": true,
            "name": "Radish",
            "price": 1.15,
            "priceInProductList": 1.15,
            "wholesalePrices": [
                {
                    "quantity": 10,
                    "price": 1.05
                }
            ],
            "compareToPrice": 1.34,
            "isShippingRequired": true,
            "weight": 0.31,
            "url": "http://app.ecwid.com/store/4870020#!/~/product/id=37208339",
            "created": "2009-07-23 17:22:37 +0000",
            "updated": "2014-07-30 10:32:37 +0000",
            "createTimestamp": 1248340746,
            "updateTimestamp": 1428313104,
            "productClassId": 0,
            "enabled": false,
            "options": [
                {
                    "type": "RADIO",
                    "name": "Size",
                    "choices": [
                        {
                            "text": "Small",
                            "priceModifier": 0,
                            "priceModifierType": "ABSOLUTE"
                        },
                        {
                            "text": "Large",
                            "priceModifier": 0.5,
                            "priceModifierType": "ABSOLUTE"
                        }
                    ],
                    "defaultChoice": 0,
                    "required": false
                },
                {
                    "type": "SELECT",
                    "name": "Color",
                    "choices": [
                        {
                            "text": "Red",
                            "priceModifier": 0,
                            "priceModifierType": "ABSOLUTE"
                        },
                        {
                            "text": "White",
                            "priceModifier": 0,
                            "priceModifierType": "ABSOLUTE"
                        }
                    ],
                    "defaultChoice": 0,
                    "required": false
                }
            ],
            "warningLimit": 0,
            "fixedShippingRateOnly": false,
            "fixedShippingRate": 0,
            "defaultCombinationId": 7084076,
            "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/3976907712.jpg",
            "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/1234123412311.jpg",
            "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341239.jpg",
            "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/4617177031.jpg",
            "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124114.jpg",
            "originalImage": {
              "url": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124114.jpg",
              "width": 123,
              "height": 456
            },
            "description": "<h5>Radish</h5>\n<p>The radish (Raphanus sativus) is an edible root vegetable of the Brassicaceae family that was domesticated in Europe in pre-Roman times. They are grown and consumed throughout the world. Radishes have numerous varieties, varying in size, color and duration of required cultivation time. There are some radishes that are grown for their seeds; oilseed radishes are grown, as the name implies, for oil production.</p>\n<p> </p>\n<div style=\"padding: 24px 24px 24px 21px; display: block; background-color: #ececec;\">From <a style=\"color: #1e7ec8; text-decoration: underline;\" title=\"Wikipedia\" href=\"http://en.wikipedia.org\">Wikipedia</a>, the free encyclopedia</div>",
            "galleryImages": [
                {
                    "id": 18276483,
                    "alt": "Radish with friends",
                    "url": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124118.jpg",
                    "thumbnail": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341231.jpg",
                    "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/3976907714.jpg",
                    "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/1234123412315.jpg",
                    "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341231.jpg",
                    "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/4617177035.jpg",
                    "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124118.jpg",
                    "width": 220,
                    "height": 293,
                    "orderby": 10
                }
            ],
            "categoryIds": [
                9691095
            ],
            "categories": [
              {
                "id": 9691095,
                "enabled": true
              }
            ],
            "seoTitle": "Radish",
            "seoDescription": "It's an awesome radish just for you!",            
            "defaultCategoryId": 9691095,
            "attributes": [
                {
                    "id": 5029057,
                    "name": "Brand",
                    "value": "SuperVegetables",
                    "type": "BRAND",
                    "show": "DESCR"
                },
                {
                    "id": 5029059,
                    "name": "Hidden Attribute",
                    "value": "Secret Value",
                    "type": "CUSTOM",
                    "show": "NOTSHOW"
                }
            ],
            "files": [
                {
                    "id": 7215101,
                    "name": "pic_200_200.jpg",
                    "description": "",
                    "size": 54492,
                    "adminUrl": "https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215101"
                },
                {
                    "id": 7215102,
                    "name": "14293004.zip",
                    "description": "Files archive",
                    "size": 18955,
                    "adminUrl": "https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215102"
                }
            ],
            "relatedProducts": {
                "productIds": [
                    37208340
                ],
                "relatedCategory": {
                    "enabled": true,
                    "categoryId": 9691095,
                    "productCount": 1
                }
            },
            "combinations": [
                {
                    "id": 7084071,
                    "combinationNumber": 6,
                    "options": [
                        {
                            "name": "Color",
                            "value": "White"
                        },
                        {
                            "name": "Size",
                            "value": "Large"
                        }
                    ],
                    "sku": "000076",
                    "quantity": 1,
                    "unlimited": false,
                    "weight": 0.41,
                    "warningLimit": 1
                },
                {
                    "id": 7084072,
                    "combinationNumber": 5,
                    "options": [
                        {
                            "name": "Color",
                            "value": "Red"
                        },
                        {
                            "name": "Size",
                            "value": "Large"
                        }
                    ],
                    "sku": "000075",
                    "quantity": 0,
                    "unlimited": false,
                    "weight": 0.41,
                    "warningLimit": 0
                },
                {
                    "id": 7084075,
                    "combinationNumber": 2,
                    "options": [
                        {
                            "name": "Size",
                            "value": "Small"
                        },
                        {
                            "name": "Color",
                            "value": "White"
                        }
                    ],
                    "sku": "000072",
                    "quantity": 67,
                    "unlimited": true,
                    "warningLimit": 0
                },
                {
                    "id": 7084076,
                    "combinationNumber": 1,
                    "options": [
                        {
                            "name": "Size",
                            "value": "Small"
                        },
                        {
                            "name": "Color",
                            "value": "Red"
                        }
                    ],
                    "sku": "000071",
                    "quantity": 61,
                    "smallThumbnailUrl": "https://app.ecwid.com/images/1003/397690841.jpg",
                    "hdThumbnailUrl": "https://app.ecwid.com/images/1003/397690842.jpg",
                    "thumbnailUrl": "https://app.ecwid.com/images/1003/397690811.jpg",
                    "imageUrl": "https://app.ecwid.com/images/1003/397690844.jpg",
                    "originalImageUrl": "https://app.ecwid.com/images/1003/397690845jpg",
                    "unlimited": false,
                    "warningLimit": 0
                }
            ],
          "dimensions": {
            "length": 14,
            "width": 6,
            "height": 3
          }
        }
    ]
}

Public token request example

GET /api/v3/4870020/products?limit=2&keyword=fruit&token=public_123abcdaASasdASjndasAnsdu HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

Response example (JSON)

{
    "total": 5,
    "count": 2,
    "offset": 0,
    "limit": 2,
    "items": [
        {
          "id": 37208339,
          "sku": "00099",
          "thumbnailUrl": "http://app.ecwid.com/default-store/00011-232-sq.jpg",
          "quantity": 11,
          "unlimited": false,
          "inStock": true,
          "name": "Orange",
          "price": 10,
          "priceInProductList": 10,
          "wholesalePrices": [
            {
              "quantity": 2,
              "price": 9
            },
            {
              "quantity": 4,
              "price": 8
            }
          ],
          "compareToPrice": 23,
          "isShippingRequired": true,
          "weight": 0,
          "url": "http://app.ecwid.com#!/Orange/p/37208339",
          "created": "2015-10-05 07:26:14 +0000",
          "updated": "2016-02-03 10:01:02 +0000",
          "createTimestamp": 1444029974,
          "updateTimestamp": 1454493662,
          "productClassId": 0,
          "enabled": true,
          "options": [],
          "warningLimit": 0,
          "fixedShippingRateOnly": true,
          "fixedShippingRate": 0,
          "defaultCombinationId": 0,
          "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
          "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341234.jpg",
          "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341232.jpg",
          "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717703.jpg",
          "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124125.jpg",
          "originalImage": {
              "url": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124125.jpg",
              "width": 123,
              "height": 456
          },
          "description": "<p>It's a tasty fruit!</p>",
          "galleryImages": [
            {
              "id": 18481471,
              "alt": "AdditionalImage",
              "url": "https://dpbfm6h358sh7.cloudfront.net/images/5035009/312058848.jpg",
              "thumbnail": "https://dpbfm6h358sh7.cloudfront.net/images/5035009/351433814.jpg",
              "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690771.jpg",
              "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/1234123412312.jpg",
              "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341235.jpg",
              "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717705.jpg",
              "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124121.jpg",
              "width": 473,
              "height": 545,
              "orderBy": 0
            },
            {
              "id": 18481472,
              "alt": "AdditionalImage",
              "url": "https://dpbfm6h358sh7.cloudfront.net/images/5035009/312058850.jpg",
              "thumbnail": "https://dpbfm6h358sh7.cloudfront.net/images/5035009/351433815.jpg",
              "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
              "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/1234123412311.jpg",
              "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341238.jpg",
              "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/4617177879.jpg",
              "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124179.jpg",
              "width": 247,
              "height": 545,
              "orderBy": 1
            }
          ],
          "categoryIds": [
            19563207,
            19976005,
            19976006
          ],
          "categories": [
            {
              "id": 19976006,
              "enabled": true
            },
            {
              "id": 19976005,
              "enabled": true
            },
            {
              "id": 19563207,
              "enabled": false
            }
          ],
          "seoTitle": "Orange",
          "seoDescription": "It's a tasty orange for you and your family!",
          "defaultCategoryId": 0,
          "favorites": {
            "count": 0,
            "displayedCount": "0"
          },
          "attributes": [
            {
              "id": 8258226,
              "name": "Width",
              "value": "61.47 mm",
              "type": "CUSTOM",
              "show": "DESCR"
            },
            {
              "id": 8258231,
              "name": "Height",
              "value": "117.09 mm",
              "type": "CUSTOM",
              "show": "DESCR"
            },
            {
              "id": 8258249,
              "name": "Depth",
              "value": "15.49 mm",
              "type": "CUSTOM",
              "show": "DESCR"
            },
            {
              "id": 8258255,
              "name": "Net weight",
              "value": "153.2 g",
              "type": "CUSTOM",
              "show": "DESCR"
            }
          ],
          "files": [],
          "relatedProducts": {
            "productIds": [],
            "relatedCategory": {
              "enabled": false,
              "categoryId": 0,
              "productCount": 1
            }
          },
          "combinations": [],
          "dimensions": {}
        },
        {
            "id": 37208339,
            "enabled": false
        }
    ]
}

A JSON object of type ‘SearchResult’ with the following fields:

SearchResult

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe total number of the items returned in this batch
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum possible number of returned items in this request.
itemsArrayThe items list

ProductEntry

FieldTypeDescription
idnumberUnique integer product identifier
skustringProduct SKU. Items with options can have several SKUs specified in the product combinations.
quantitynumberAmount of product items in stock. This field is omitted for the products with unlimited stock
unlimitedboolean true if the product has unlimited stock
inStockboolean true if the product or any of its combinations is in stock (quantity is more than zero) or has unlimited quantity. false otherwise.
namestringProduct title
pricenumberBase product price
priceInProductListnumberProduct price displayed in a storefront. May differ from the price value when the product has combinations and the default combination’s price is different from the base product price
wholesalePricesArray<WholesalePrice>Sorted array of wholesale price tiers (quantity limit and price pairs)
compareToPricenumberProduct’s sale price displayed strike-out in the customer frontend Omitted if empty
isShippingRequiredboolean true if product requires shipping, false otherwise
weightnumberProduct weight in the units defined in store settings. Omitted for intangible products
urlstringURL of the product’s details page in the store. Learn more
createdstringDate and time of the product creation. Example: 2014-07-30 10:32:37 +0000
updatedstringProduct last update date/time
createTimestampnumberThe date of product creation in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberProduct last update date in UNIX Timestamp format, e.g 1427268654
productClassIdnumberId of the class (type) that this product belongs to. 0 value means the product is of the default 'General’ class. See also: Product types and attributes in Ecwid
enabledboolean true if product is enabled, false otherwise. Disabled products are not displayed in the store front.
optionsArray<ProductOption>A list of the product options. Empty ([]) if no options are specified for the product.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock, if set. When the product quantity reaches this level, the store administrator gets an email notification.
fixedShippingRateOnlyboolean true if shipping cost for this product is calculated as 'Fixed rate per item’ (managed under the “Tax and Shipping” section of the product management page in Ecwid Control panel). false otherwise. With this option on, the fixedShippingRate field specifies the shipping cost of the product
fixedShippingRatenumberWhen fixedShippingRateOnly is true, this field sets the product fixed shipping cost per item. When fixedShippingRateOnly is false, the value in this field is treated as an extra shipping cost the product adds to the global calculated shipping
defaultCombinationIdnumberIdentifier of the default product combination, which is defined by the default values of product options.
thumbnailUrlstringURL of the product thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of the biggest dimension is 400px. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product image resized to fit 1500x1500px. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product thumbnail resized to fit 160x160px. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct HD thumbnail URL resized to fit 800x800px
originalImageUrlstringURL of the original not resized product image
originalImage<ImageDetails>Details of the product image
descriptionstringProduct description in HTML
galleryImagesArray<GalleryImage>List of the product gallery images
categoryIdsArray<number>List of the categories, which the product belongs to. If no categories provided, product belogs to store front page, see showOnFrontpage field
categoriesArray<CategoriesInfo>List of the categories, which the product belongs to, with brief details. If no categories provided, product belogs to store front page, see showOnFrontpage field
seoTitlestringPage title to be displayed in search results on the web. Recommended length is under 55 characters
seoDescriptionstringPage description to be displayed in search results on the web. Recommended length is under 160 characters
defaultCategoryIdnumberIdentifier of the default category of the product
favorites<FavoritesStats>Product favorites stats
attributesArray<AttributeValue>Product attributes and their values
filesArray<ProductFile>Downloadable files (E-goods) attached to the product
relatedProducts<RelatedProducts>Related or “You may also like” products of the product
combinationsArray<Combination>List of the product combinations
dimensions<ProductDimensions>Product dimensions info
showOnFrontpagenumberIf not null, the position (index) of a product in the store front page. If null, then product is not shown in the store front page

FavoritesStats

FieldTypeDescription
countnumberThe actual number of 'likes’ of this product
displayedCountstringThe displayed number of likes. May differ from the count if, for example, the value is more than 1000, than it will show 1K instead of the precise number

WholesalePrice

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

ProductOption

FieldTypeDescription
typestringOne of SELECT, RADIO, CHECKBOX, TEXTFIELD, TEXTAREA, DATE, FILES
namestringProduct option name, e.g. Color
choicesArray<ProductOptionChoice>All possible option selections for the types SELECT, CHECKBOX or RADIO. This field is omitted for the product option with no selection (e.g. text, datepicker or upload file options)
defaultChoicenumberThe number, starting from 0, of the option’s default selection. Only presents if the type is SELECT, CHECKBOX or RADIO.
requiredboolean true if this option is required, false otherwise. Default is false

ImageDetails

FieldTypeDescription
urlstringImage URL
widthintegerImage width
heightintegerImage height

GalleryImage

FieldTypeDescription
idnumberInternal gallery image ID
altstringImage description, displayed in the image tag’s alt attribute
urlstring Deprecated. Original image URL. Equals originalImageUrl
thumbnailstring Deprecated. Image thumbnail URL resized to fit 160x160px. Equals smallThumbnailUrl
thumbnailUrlstringURL of the product thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of the biggest dimension is 400px. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product image resized to fit 1500x1500px. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product thumbnail resized to fit 160x160px. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct HD thumbnail URL resized to fit 800x800px
originalImageUrlstringURL of the original not resized product image
widthnumberImage width
heightnumberImage height
orderbynumberThe sort weight of the image in the gallery images list. The less the number, the closer the image to the beginning of the gallery

CategoriesInfo

FieldTypeDescription
idnumberCategory ID
enabledboolean true if category is enabled, false otherwise

AttributeValue

FieldTypeDescription
idnumberUnique attribute ID. See Product Classes for the information on attribute IDs
namestringAttribute displayed name
valuestringAttribute value
typestringAttribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: CUSTOM, UPC, BRAND, GENDER, AGE_GROUP, COLOR, SIZE, PRICE_PER_UNIT, UNITS_IN_PRODUCT
showstringDefines where to display the product attribute value:. Supported values: NOTSHOW, DESCR, PRICE

ProductFile

FieldTypeDescription
idnumberInternal ID of the file
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringDirect link to the file. Important: to download the file, add your API token to this URL like this: https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215102?token=YOUR-API-TOKEN

RelatedProducts

FieldTypeDescription
productIdsArray<number>IDs of the related products
relatedCategoryRelatedCategoryDescribes the “N random related products from a category” option

RelatedCategory

FieldTypeDescription
enabledboolean true if the “N random related products from a category” option is enabled. false otherwise
categoryIdnumberId of the related category. Zero value means “any category”, that is, random products from the whole store.
productCountnumberNumber of random products from the given category to be shown as related

Combination

FieldTypeDescription
idnumberCombination ID
combinationNumbernumberCombination # number, which is displayed in the combinations table in Control panel
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
thumbnailUrlstringURL of the product combination thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product combination image resized to fit 1500x1500px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product combination thumbnail resized to fit 160x160px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct combination HD thumbnail URL resized to fit 800x800px. Omitted if the combination inherits the base product’s image.
originalImageUrlstringURL of the original not resized product combination image. Omitted if the combination inherits the base product’s image.
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedboolean true if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination inherits the base product’s settings.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

ProductOptionChoice

FieldTypeDescription
textstringOption selection text, e.g. 'Green’.
priceModifiernumberPercent or absolute value of the option’s price markup. Positive, negative and zero values are allowed. Default is 0
priceModifierTypestringOption markup calculation type. PERCENT or ABSOLUTE. Default is ABSOLUTE.

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

Errors

Error response example

HTTP/1.1 400 Wrong parameter 'inStock' value: expected one of 'true', 'false', 'yes', 'no', 'on', 'off', '1', '0
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaningCode (optional)
400Request parameters are malformed
400The cleanUrls value is invalid. It must be either true or falseCLEAN_URLS_PARAMETER_IS_INVALID
415Unsupported content-type: expected application/json or text/json
500Cannot get the product because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Q: How to get URLs for products?

Direct URL for each product is always available in the url field once you make a request to the Ecwid REST API.

In any Ecwid store there is a storefront URL field, where store owners can specify their storefront location. In case if it’s empty, Ecwid will use their starter site URL to provide product URLs in the REST API and other connected services.

When a store is embedded into multiple websites

For this situation you may need to generate a product feed for each of those websites (building a sitemap, etc.), hence there will be multiple storefront URLs to process. In this case you can use baseUrl request parameter to get a working product URL in a response from the Ecwid REST API.

Let’s see how it works:

If baseUrl request parameter is specified, then the url field will be generated according to that URL as a storefront URL.

Examples

Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com":

  • baseUrl parameter is not set in a request:

Example product URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • baseUrl parameter is set as "https://mycoolstore.com":

Example product URL in the url field will be: "https://mycoolstore.com#!/apple/p/70445445"

As you can see, the product URL in a response from Ecwid API changes based on the value of the baseUrl request parameter. So now you can use it to get product URLs of the same store for any number of storefront URLs.

It is possible to use the baseUrl parameter together with the cleanUrls parameter. See below for more details on the cleanUrls parameter.

Receiving SEO-friendly (clean) URLs from the Ecwid REST API

By default, Ecwid’s product URLs use hash-based format: "https://mdemo.ecwid.com#!/apple/p/70445445". In case if a website supports the SEO-friendly (clean) URLs, you will need to use the cleanUrls request parameter in order to get URLs in that format.

Let’s see how it works:

If cleanUrls request parameter is set to true, then url field will have the SEO-friendly format in the response (clean URL, no hash “#”).

Examples

Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com"

  • cleanUrls parameter is set to false or not set

Example product URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • cleanUrls parameter is set to true

Example product URL in the url field will be: "https://mdemo.ecwid.com/apple-p70445445"

As you can see, the format of a product URL returned from the Ecwid API changes based on the cleanUrls request parameter. So now you can use it to get URLs of any of the two supported URL formats - SEO-friendly (clean) URLs or hash-based URLs.

It is possible to use the cleanUrls parameter together with the baseUrl parameter. See above for more details on the baseUrl parameter.

Get a product

This method allows you to get all details of a specific product in an Ecwid store.

Q: How can I request details of several products at once?

If you need to do this operation for multiple products at once (batch request), you can use the Search products method: provide the productIds you have in the productId parameter separating them with a comma.

This way your app will save some time as you will be performing less requests to the Ecwid API and they will be much more efficient.

Request

Request example

GET /api/v3/4870020/products/123123?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/products/{productId}?token={token}&baseUrl={baseUrl}&cleanUrls={cleanUrls}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token
baseUrlstringStorefront URL for Ecwid to use when returning product URLs in the url field. If not specified, Ecwid will use the storefront URL specified in the store settings
cleanUrlsbooleanIf true, Ecwid will return the SEO-friendly clean URL (without hash '#') in the url field. If false, Ecwid will return URL in the old format (with hash '#'). We recommend using true value if merchant’s website supports clean SEO-friendly URL feature

Response

Response example (JSON)

{
    "id": 37208339,
    "sku": "00007",
    "thumbnailUrl": "http://app.ecwid.com/default-store/00007-230-sq.jpg",
    "quantity": 67,
    "inStock": true,
    "name": "Radish",
    "price": 1.15,
    "priceInProductList": 1.15,
    "wholesalePrices": [
        {
            "quantity": 10,
            "price": 1.05
        }
    ],
    "compareToPrice": 1.34,
    "isShippingRequired": true,
    "weight": 0.31,
    "url": "http://app.ecwid.com/store/4870020#!/~/product/id=37208339",
    "created": "2009-07-23 17:22:37 +0000",
    "updated": "2014-07-30 10:32:37 +0000",
    "createTimestamp": 1248340746,
    "updateTimestamp": 1428313104,
    "productClassId": 0,
    "enabled": true,
    "options": [
        {
            "type": "RADIO",
            "name": "Size",
            "choices": [
                {
                    "text": "Small",
                    "priceModifier": 0,
                    "priceModifierType": "ABSOLUTE"
                },
                {
                    "text": "Large",
                    "priceModifier": 0.5,
                    "priceModifierType": "ABSOLUTE"
                }
            ],
            "defaultChoice": 0,
            "required": false
        },
        {
            "type": "SELECT",
            "name": "Color",
            "choices": [
                {
                    "text": "Red",
                    "priceModifier": 0,
                    "priceModifierType": "ABSOLUTE"
                },
                {
                    "text": "White",
                    "priceModifier": 0,
                    "priceModifierType": "ABSOLUTE"
                }
            ],
            "defaultChoice": 0,
            "required": false
        }
    ],
    "warningLimit": 0,
    "fixedShippingRateOnly": false,
    "fixedShippingRate": 0,
    "defaultCombinationId": 7084076,
    "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/3976907712.jpg",
    "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/1234123412311.jpg",
    "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341239.jpg",
    "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/4617177031.jpg",
    "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124114.jpg",
    "originalImage": {
      "url": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124114.jpg",
      "width": 123,
      "height": 456
    },
    "description": "<h5>Radish</h5>\n<p>The radish (Raphanus sativus) is an edible root vegetable of the Brassicaceae family that was domesticated in Europe in pre-Roman times. They are grown and consumed throughout the world. Radishes have numerous varieties, varying in size, color and duration of required cultivation time. There are some radishes that are grown for their seeds; oilseed radishes are grown, as the name implies, for oil production.</p>\n<p> </p>\n<div style=\"padding: 24px 24px 24px 21px; display: block; background-color: #ececec;\">From <a style=\"color: #1e7ec8; text-decoration: underline;\" title=\"Wikipedia\" href=\"http://en.wikipedia.org\">Wikipedia</a>, the free encyclopedia</div>",
    "galleryImages": [
      {
        "id": 18276483,
        "alt": "Radish with friends",
        "url": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124118.jpg",
        "thumbnail": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341231.jpg",
        "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/3976907714.jpg",
        "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/1234123412315.jpg",
        "smallThumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341231.jpg",
        "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/4617177035.jpg",
        "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124118.jpg",
        "width": 220,
        "height": 293,
        "orderby": 10
      }
    ],
    "categoryIds": [
        9691095
    ],
    "categories": [
      {
        "id": 9691095,
        "enabled": true
      }
    ],
    "seoTitle": "Radish",
    "seoDescription": "It's an awesome radish just for you!",     
    "defaultCategoryId": 9691095,
    "attributes": [
        {
            "id": 5029057,
            "name": "Brand",
            "value": "SuperVegetables",
            "type": "BRAND",
            "show": "DESCR"
        },
        {
            "id": 5029059,
            "name": "Hidden Attribute",
            "value": "Secret Value",
            "type": "CUSTOM",
            "show": "NOTSHOW"
        }
    ],
    "files": [
        {
            "id": 7215101,
            "name": "pic_200_200.jpg",
            "description": "",
            "size": 54492,
            "adminUrl": "https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215101"
        },
        {
            "id": 7215102,
            "name": "14293004.zip",
            "description": "Files archive",
            "size": 18955,
            "adminUrl": "https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215102"
        }
    ],
    "relatedProducts": {
        "productIds": [
            37208340
        ],
        "relatedCategory": {
            "enabled": true,
            "categoryId": 9691095,
            "productCount": 1
        }
    },
    "combinations": [
        {
            "id": 7084071,
            "combinationNumber": 6,
            "options": [
                {
                    "name": "Color",
                    "value": "White"
                },
                {
                    "name": "Size",
                    "value": "Large"
                }
            ],
            "sku": "000076",
            "quantity": 1,
            "unlimited": false,
            "weight": 0.41,
            "warningLimit": 1
        },
        {
            "id": 7084072,
            "combinationNumber": 5,
            "options": [
                {
                    "name": "Color",
                    "value": "Red"
                },
                {
                    "name": "Size",
                    "value": "Large"
                }
            ],
            "sku": "000075",
            "quantity": 0,
            "unlimited": false,
            "weight": 0.41,
            "warningLimit": 0
        },
        {
            "id": 7084075,
            "combinationNumber": 2,
            "options": [
                {
                    "name": "Size",
                    "value": "Small"
                },
                {
                    "name": "Color",
                    "value": "White"
                }
            ],
            "sku": "000072",
            "quantity": 67,
            "unlimited": true,
            "warningLimit": 0
        },
        {
            "id": 7084076,
            "combinationNumber": 1,
            "options": [
                {
                    "name": "Size",
                    "value": "Small"
                },
                {
                    "name": "Color",
                    "value": "Red"
                }
            ],
            "sku": "000071",
            "quantity": 61,
            "unlimited": false,
            "warningLimit": 0
        }
    ],
    "dimensions": {
      "length": 0,
      "width": 0,
      "height": 0
    },
    "showOnFrontpage": 2
}

Public token request example for disabled product

GET /api/v3/4870020/products/66722482?token=public_123abcdaASasdASjndasAnsdu HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

Response example (JSON)

{
  "id": 66722482,
  "enabled": false
}

A JSON object of type 'Product’ with the following fields:

Product

FieldTypeDescription
idnumberUnique integer product identifier
skustringProduct SKU. Items with options can have several SKUs specified in the product combinations.
quantitynumberAmount of product items in stock. This field is omitted for the products with unlimited stock
unlimitedboolean true if the product has unlimited stock
inStockboolean true if the product or any of its combinations is in stock (quantity is more than zero) or has unlimited quantity. false otherwise.
namestringProduct title
pricenumberBase product price
priceInProductListnumberProduct price displayed in a storefront. May differ from the price value when the product has combinations and the default combination’s price is different from the base product price
wholesalePricesArray<WholesalePrice>Sorted array of wholesale price tiers (quantity limit and price pairs)
compareToPricenumberProduct’s sale price displayed strike-out in the customer frontend Omitted if empty
isShippingRequiredboolean true if product requires shipping, false otherwise
weightnumberProduct weight in the units defined in store settings. Omitted for intangible products
urlstringURL of the product’s details page in the store. Learn more
createdstringDate and time of the product creation. Example: 2014-07-30 10:32:37 +0000
updatedstringProduct last update date/time
createTimestampnumberThe date of product creation in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberProduct last update date in UNIX Timestamp format, e.g 1427268654
productClassIdnumberId of the class (type) that this product belongs to. 0 value means the product is of the default 'General’ class. See also: Product types and attributes in Ecwid
enabledboolean true if product is enabled, false otherwise. Disabled products are not displayed in the store front.
optionsArray<ProductOption>A list of the product options. Empty ([]) if no options are specified for the product.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock, if set. When the product quantity reaches this level, the store administrator gets an email notification.
fixedShippingRateOnlyboolean true if shipping cost for this product is calculated as 'Fixed rate per item’ (managed under the “Tax and Shipping” section of the product management page in Ecwid Control panel). false otherwise. With this option on, the fixedShippingRate field specifies the shipping cost of the product
fixedShippingRatenumberWhen fixedShippingRateOnly is true, this field sets the product fixed shipping cost per item. When fixedShippingRateOnly is false, the value in this field is treated as an extra shipping cost the product adds to the global calculated shipping
defaultCombinationIdnumberIdentifier of the default product combination, which is defined by the default values of product options.
thumbnailUrlstringURL of the product thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product image resized to fit 1500x1500px. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product thumbnail resized to fit 160x160px. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct HD thumbnail URL resized to fit 800x800px
originalImageUrlstringURL of the original not resized product image
originalImage<ImageDetails>Details of the product image
descriptionstringProduct description in HTML
galleryImagesArray<GalleryImage>List of the product gallery images
categoryIdsArray<number>List of the categories, which the product belongs to. If no categories provided, product belogs to store front page, see showOnFrontpage field
categoriesArray<CategoriesInfo>List of the categories, which the product belongs to, with brief details. If no categories provided, product belogs to store front page, see showOnFrontpage field
seoTitlestringPage title to be displayed in search results on the web. Recommended length is under 55 characters
seoDescriptionstringPage description to be displayed in search results on the web. Recommended length is under 160 characters
defaultCategoryIdnumberIdentifier of the default category of the product
favorites<FavoritesStats>Product favorites stats
attributesArray<AttributeValue>Product attributes and their values
filesArray<ProductFile>Downloadable files (E-goods) attached to the product
relatedProducts<RelatedProducts>Related or “You may also like” products of the product
combinationsArray<Combination>List of the product combinations
dimensions<ProductDimensions>Product dimensions info
showOnFrontpagenumberIf not null, the position (index) of a product in the store front page. If null, then product is not shown in the store front page

FavoritesStats

FieldTypeDescription
countnumberThe actual number of 'likes’ of this product
displayedCountstringThe displayed number of likes. May differ from the count if, for example, the value is more than 1000, than it will show 1K instead of the precise number

WholesalePrice

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

ProductOption

FieldTypeDescription
typestringOne of SELECT, RADIO, CHECKBOX, TEXTFIELD, TEXTAREA, DATE, FILES
namestringProduct option name, e.g. Color
choicesArray<ProductOptionChoice>All possible option selections for the types SELECT, CHECKBOX or RADIO. This field is omitted for the product option with no selection (e.g. text, datepicker or upload file options)
defaultChoicenumberThe number, starting from 0, of the option’s default selection. Only presents if the type is SELECT, CHECKBOX or RADIO.
requiredboolean true if this option is required, false otherwise. Default is false

ImageDetails

FieldTypeDescription
urlstringImage URL
widthintegerImage width
heightintegerImage height

GalleryImage

FieldTypeDescription
idnumberInternal gallery image ID
altstringImage description, displayed in the image tag’s alt attribute
urlstring Deprecated. Original image URL. Equals originalImageUrl
thumbnailstring Deprecated. Image thumbnail URL resized to fit 160x160px. Equals smallThumbnailUrl
thumbnailUrlstringURL of the product thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product image resized to fit 1500x1500px. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product thumbnail resized to fit 160x160px. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct HD thumbnail URL resized to fit 800x800px
originalImageUrlstringURL of the original not resized product image
widthnumberImage width
heightnumberImage height
orderbynumberThe sort weight of the image in the gallery images list. The less the number, the closer the image to the beginning of the gallery

CategoriesInfo

FieldTypeDescription
idnumberCategory ID
enabledboolean true if category is enabled, false otherwise

AttributeValue

FieldTypeDescription
idnumberUnique attribute ID. See Product Classes for the information on attribute IDs
namestringAttribute displayed name
valuestringAttribute value
typestringAttribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: CUSTOM, UPC, BRAND, GENDER, AGE_GROUP, COLOR, SIZE, PRICE_PER_UNIT, UNITS_IN_PRODUCT
showstringDefines where to display the product attribute value:. Supported values: NOTSHOW, DESCR, PRICE .

ProductFile

FieldTypeDescription
idnumberInternal ID of the file
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringDirect link to the file. Important: to download the file, add your API token to this URL like this: https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215102?token=YOUR-API-TOKEN

RelatedProducts

FieldTypeDescription
productIdsArray<number>IDs of the related products
relatedCategoryRelatedCategoryDescribes the “N random related products from a category” option

RelatedCategory

FieldTypeDescription
enabledboolean true if the “N random related products from a category” option is enabled. false otherwise
categoryIdnumberId of the related category. Zero value means “any category”, that is, random products from the whole store.
productCountnumberNumber of random products from the given category to be shown as related

Combination

FieldTypeDescription
idnumberCombination ID
combinationNumbernumberCombination # number, which is displayed in the combinations table in Control panel
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
thumbnailUrlstringURL of the product combination thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product combination image resized to fit 1500x1500px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product combination thumbnail resized to fit 160x160px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct combination HD thumbnail URL resized to fit 800x800px. Omitted if the combination inherits the base product’s image.
originalImageUrlstringURL of the original not resized product combination image. Omitted if the combination inherits the base product’s image.
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedboolean true if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination inherits the base product’s settings.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

ProductOptionChoice

FieldTypeDescription
textstringOption selection text, e.g. 'Green’.
priceModifiernumberPercent or absolute value of the option’s price markup. Positive, negative and zero values are allowed. Default is 0
priceModifierTypestringOption markup calculation type. PERCENT or ABSOLUTE. Default is ABSOLUTE.

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

Errors

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaningCode (optional)
400The cleanUrls value is invalid. It must be either true or falseCLEAN_URLS_PARAMETER_IS_INVALID
404Product is not found
500Cannot get the product because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Q: How to get URLs for products?

Direct URL for each product is always available in the url field once you make a request to the Ecwid REST API.

In any Ecwid store there is a storefront URL field, where store owners can specify their storefront location. In case if it’s empty, Ecwid will use their starter site URL to provide product URLs in the REST API and other connected services.

When a store is embedded into multiple websites

For this situation you may need to generate a product feed for each of those websites (building a sitemap, etc.), hence there will be multiple storefront URLs to process. In this case you can use baseUrl request parameter to get a working product URL in a response from the Ecwid REST API.

Let’s see how it works:

If baseUrl request parameter is specified, then the url field will be generated according to that URL as a storefront URL.

Examples

Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com":

  • baseUrl parameter is not set in a request:

Example product URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • baseUrl parameter is set as "https://mycoolstore.com":

Example product URL in the url field will be: "https://mycoolstore.com#!/apple/p/70445445"

As you can see, the product URL in a response from Ecwid API changes based on the value of the baseUrl request parameter. So now you can use it to get product URLs of the same store for any number of storefront URLs.

It is possible to use the baseUrl parameter together with the cleanUrls parameter. See below for more details on the cleanUrls parameter.

Receiving SEO-friendly (clean) URLs from the Ecwid REST API

By default, Ecwid’s product URLs use hash-based format: "https://mdemo.ecwid.com#!/apple/p/70445445". In case if a website supports the SEO-friendly (clean) URLs, you will need to use the cleanUrls request parameter in order to get URLs in that format.

Let’s see how it works:

If cleanUrls request parameter is set to true, then url field will have the SEO-friendly format in the response (clean URL, no hash “#”).

Examples

Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com"

  • cleanUrls parameter is set to false or not set

Example product URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • cleanUrls parameter is set to true

Example product URL in the url field will be: "https://mdemo.ecwid.com/apple-p70445445"

As you can see, the format of a product URL returned from the Ecwid API changes based on the cleanUrls request parameter. So now you can use it to get URLs of any of the two supported URL formats - SEO-friendly (clean) URLs or hash-based URLs.

It is possible to use the cleanUrls parameter together with the baseUrl parameter. See above for more details on the baseUrl parameter.

Add a product

Request

Request body

POST /api/v3/4870020/products?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
  "sku": "000012199",
  "quantity": 10,
  "name": "New Product",
  "price": 20.99,
  "compareToPrice": 24.99,
  "isShippingRequired": false,
  "categoryIds": [
    9691094
  ],
  "weight": 10,
  "enabled": true,
  "description": "A <b>new</b> product description",
  "productClassId": 0,
  "created":"2014-01-01",
  "fixedShippingRateOnly": false,
  "fixedShippingRate": 1.2
}

POST https://app.ecwid.com/api/v3/{storeId}/products?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'Product’ with the following fields:

Product

FieldTypeDescription
namestringProduct title
skustringProduct SKU. If this field is empty, Ecwid will generate new unique SKU automatically.
quantitynumberAmount of product items in stock.
unlimitedbooleanSet as true to make Unlimited stock for the product and to not track product inventory.
pricenumberBase product price
wholesalePricesArray<WholesalePrice>Sorted array of wholesale price tiers (quantity limit and price pairs)
compareToPricenumberProduct’s sale price displayed strike-out in the customer frontend
isShippingRequiredboolean true if product requires shipping, false otherwise
weightnumberProduct weight in the units defined in store settings. Leave empty for intangible products
productClassIdnumberId of the class (type) that this product belongs to. 0 value means the product is of the default 'General’ class. See also: Product types and attributes in Ecwid
enabledboolean true to make product enabled, false otherwise. Disabled products are not displayed in the store front.
optionsArray<ProductOption>List of the product options.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock, if set. When the product quantity reaches this level, the store administrator gets an email notification.
fixedShippingRateOnlyboolean true if shipping cost for this product is calculated as 'Fixed rate per item’ (managed under the “Tax and Shipping” section of the product management page in Ecwid Control panel). false otherwise. With this option on, the fixedShippingRate field specifies the shipping cost of the product
fixedShippingRatenumberWhen fixedShippingRateOnly is true, this field sets the product fixed shipping cost per item. When fixedShippingRateOnly is false, the value in this field is treated as an extra shipping cost the product adds to the global calculated shipping
descriptionstringProduct description in HTML
categoryIdsArray<number>List of the categories, which the product belongs to. If no categories provided, product belogs to store front page, see showOnFrontpage field
seoTitlestringPage title to be displayed in search results on the web. Recommended length is under 55 characters
seoDescriptionstringPage description to be displayed in search results on the web. Recommended length is under 160 characters
defaultCategoryIdnumberIdentifier of the default category of the product
attributesArray<AttributeValue>Product attributes and their values
relatedProducts<RelatedProducts>Related or “You may also like” products of the product
dimensions<ProductDimensions>Product dimensions info
showOnFrontpagenumberIf not null, the position (index) of a product in the store front page. If null, then product is not shown in the store front page

WholesalePrice

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

ProductOption

FieldTypeDescription
typestringOne of SELECT, RADIO, CHECKBOX, TEXTFIELD, TEXTAREA, DATE, FILES
namestringProduct option name, e.g. Color
choicesArray<ProductOptionChoice>All possible option selections for the types SELECT, CHECKBOX or RADIO. Omit this field for product options with no selection (e.g. text, datepicker or upload file options)
defaultChoicenumberThe number, starting from 0, of the option’s default selection for the options types SELECT, CHECKBOX or RADIO.
requiredboolean true if this option is required, false otherwise. Default is false

AttributeValue

FieldTypeDescription
idnumberUnique attribute ID. See Product Classes for the information on attribute IDs.
aliasstringOne of UPC , BRAND . This can be used instead of id to quickly set the basic product attributes values without numeric id: UPC and brand
valuestringAttribute value

RelatedProducts

FieldTypeDescription
productIdsArray<number>IDs of the related products, sort order is taken into the account
relatedCategoryRelatedCategoryDescribes the “N random related products from a category” option

RelatedCategory

FieldTypeDescription
enabledboolean true if the “N random related products from a category” option is enabled. false otherwise
categoryIdnumberId of the related category. Zero value means “any category”, that is, random products from the whole store.
productCountnumberNumber of random products from the given category to be shown as related

OptionValue

FieldTypeDescription
namestringOption name, as in Product.options[i].name
valuestringOption value one of Product.options[i].choices[j].text

ProductOptionChoice

FieldTypeDescription
textstringOption selection text, e.g. 'Green’.
priceModifiernumberPercent or absolute value of the option’s price markup. Positive, negative and zero values are allowed. Default is 0
priceModifierTypestringOption markup calculation type. PERCENT or ABSOLUTE. Default is ABSOLUTE.

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

Response

Response example

{
    "id": 39766764
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberID of the created product

Errors

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

{
 errorMessage: "WhosalePrice cannot be null",
 errorCode: "WHOLESALE_PRICES_CANT_BE_NULL"
}

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescriptionCode (optional)
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
402The merchant plan product limit is reached
404Some of the linked entities in the request doesn’t exist. For example, the product class is not found
409The product with such SKU already existsSKU_ALREADY_EXISTS
409Specified wholesale price can’t be nullWHOLESALE_PRICES_CANT_BE_NULL
409Specified wholesale price can’t be negativeWHOLESALE_PRICES_CANT_BE_NEGATIVE
409Specified wholesale price is too bigWHOLESALE_PRICES_TOO_BIG
409Specified wholesale price quantity is too smallWHOLESALE_PRICES_QUANTITY_TOO_SMALL
415Unsupported content-type: expected application/json or text/json

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
errorCodestringError code

Update a product

Request example

PUT /api/v3/4870020/products/39766764?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
  "compareToPrice": 24.99,
  "categoryIds": [
    9691094
  ],
  "attributes": [
    {
      "id": 12974019,
      "name": "Brand",
      "value": "Apple",
      "show": "DESCR"
    }
  ]
}

PUT https://app.ecwid.com/api/v3/{storeId}/products/{productId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token

Request body

A JSON object of type 'Product’ with the following fields:

Product

FieldTypeDescription
skustringProduct SKU
namestringProduct title
quantitynumberAmount of product items in stock.
unlimitedbooleanSet as true to make Unlimited stock for the product and to not track product inventory.
pricenumberBase product price
wholesalePricesArray<WholesalePrice>Sorted array of wholesale price tiers (quantity limit and price pairs)
compareToPricenumberProduct’s sale price displayed strike-out in the customer frontend
isShippingRequiredboolean true if product requires shipping, false otherwise
weightnumberProduct weight in the units defined in store settings. Leave empty for intangible products
productClassIdnumberId of the product type that this product belongs to. 0 value means the product is of the default 'General’ type. See also: Product types and attributes in Ecwid
enabledboolean true to make product enabled, false otherwise. Disabled products are not displayed in the store front.
optionsArray<ProductOption>List of the product options.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock, if set. When the product quantity reaches this level, the store administrator gets an email notification.
fixedShippingRateOnlyboolean true if shipping cost for this product is calculated as 'Fixed rate per item’ (managed under the “Tax and Shipping” section of the product management page in Ecwid Control panel). false otherwise. With this option on, the fixedShippingRate field specifies the shipping cost of the product
fixedShippingRatenumberWhen fixedShippingRateOnly is true, this field sets the product fixed shipping cost per item. When fixedShippingRateOnly is false, the value in this field is treated as an extra shipping cost the product adds to the global calculated shipping
descriptionstringProduct description in HTML
categoryIdsArray<number>List of the categories, which the product belongs to. If no categories provided, product belogs to store front page, see showOnFrontpage field
seoTitlestringPage title to be displayed in search results on the web. Recommended length is under 55 characters
seoDescriptionstringPage description to be displayed in search results on the web. Recommended length is under 160 characters
defaultCategoryIdnumberIdentifier of the default category of the product
attributesArray<AttributeValue>Product attributes and their values
relatedProducts<RelatedProducts>Related or “You may also like” products of the product
galleryImagesArray<GalleryImage>List of the product gallery images (for updating alt tags and sort order)
dimensions<ProductDimensions>Product dimensions info
showOnFrontpagenumberIf not null, the position (index) of a product in the store front page. If null, then product is not shown in the store front page

WholesalePrice

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

ProductOption

FieldTypeDescription
typestringOne of SELECT, RADIO, CHECKBOX, TEXTFIELD, TEXTAREA, DATE, FILES
namestringProduct option name, e.g. Color
choicesArray<ProductOptionChoice>All possible option selections for the types SELECT, CHECKBOX or RADIO. Omit this field for product options with no selection (e.g. text, datepicker or upload file options)
defaultChoicenumberThe number, starting from 0, of the option’s default selection for the options types SELECT, CHECKBOX or RADIO.
requiredboolean true if this option is mandatory, false otherwise. Default is false

AttributeValue

FieldTypeDescription
idnumberUnique attribute ID. See Product Types for the information on attribute IDs.
aliasstringOne of UPC , BRAND . This can be used instead of id to quickly update the basic product attributes without numeric id: UPC and brand
valuestringAttribute value

RelatedProducts

FieldTypeDescription
productIdsArray<number>IDs of the related products, sort order is taken into the account
relatedCategoryRelatedCategoryDescribes the “N random related products from a category” option

RelatedCategory

FieldTypeDescription
enabledboolean true if the “N random related products from a category” option is enabled. false otherwise
categoryIdnumberId of the related category. Zero value means “any category”, that is, random products from the whole store.
productCountnumberNumber of random products from the given category to be shown as related

OptionValue

FieldTypeDescription
namestringOption name, as in Product.options[i].name
valuestringOption value one of Product.options[i].choices[j].text

ProductOptionChoice

FieldTypeDescription
textstringOption selection text, e.g. 'Green’.
priceModifiernumberPercent or absolute value of the option’s price markup. Positive, negative and zero values are allowed. Default is 0
priceModifierTypestringOption markup calculation type. PERCENT or ABSOLUTE. Default is ABSOLUTE.

GalleryImage

FieldTypeDescription
idnumberInternal gallery image ID
altstringImage description, displayed in the image tag’s alt attribute
orderbynumberThe sort weight of the image in the gallery images list. The less the number, the closer the image to the beginning of the gallery

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

Response

Response example (JSON)

{
  "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated products (1 or 0 depending on whether the update was successful)

Errors

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

{
 errorMessage: "WhosalePrice cannot be null",
 errorCode: "WHOLESALE_PRICES_CANT_BE_NULL"
}

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescriptionCode (optional)
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
402The merchant plan product limit is reached
404Some of the linked entities in the request doesn’t exist. For example, the product class is not found
409The product with such SKU already existsSKU_ALREADY_EXISTS
409Specified wholesale price can’t be nullWHOLESALE_PRICES_CANT_BE_NULL
409Specified wholesale price can’t be negativeWHOLESALE_PRICES_CANT_BE_NEGATIVE
409Specified wholesale price is too bigWHOLESALE_PRICES_TOO_BIG
409Specified wholesale price quantity is too smallWHOLESALE_PRICES_QUANTITY_TOO_SMALL
415Unsupported content-type: expected application/json or text/json

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
errorCodestringError code

Adjust product inventory

Request example

PUT /api/v3/4870020/products/39766764/inventory?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
    "quantityDelta": -10
}

When your integration changes in stock quantity of products in a store pretty often, it becomes harder and harder to keep track of how many items are actually in stock. For example, when at one point of time you have 3 items in stock and 5 in the very next second, then using the specific values can result in incorrect stock quantity.

This method solves this very problem: you can increase or decrease the product’s stock quantity by a delta quantity. For example, if you need to decrease quantity by 10 items, you can use this method.

This method is also available for the product combinations.

PUT https://app.ecwid.com/api/v3/{storeId}/products/{productId}/inventory?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token

Request body

A JSON object of type 'Inventory’ with the following fields:

Inventory

FieldTypeDescription
quantityDeltanumberDelta value used to update product quantity. Negative value will decrease quantity, positive one will increase it.

Response

Response example (JSON)

{
  "updateCount": 1
}

A JSON object of type 'InventoryAdjustmentStatus’ with the following fields:

InventoryAdjustmentStatus

FieldTypeDescription
updateCountnumberThe number of updated products (1 or 0 depending on whether the update was successful)
warningstringInventory update warning(optional). For example, the warning will display if the stock became negative

Errors

HTTP/1.1 400 Bad Request
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
404Product not found
415Unsupported content-type: expected application/json or text/json
500Could not process the request, internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete a product

Request example

DELETE /api/v3/4870020/products/39847403?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount":1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted products (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 400 Bad request
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
500The delete request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload product image

Upload product image: if the product already has an image attached, the uploaded image will replace the existing one. Maximum allowed file size is 20Mb.

Request example

POST /api/v3/4870020/products/1234657/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/products/123456/image?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/products/123456/image?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/products/{productId}/image?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token

When uploading an image for a product, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
    "id": 240198557
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal image ID

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

{
    "errorMessage": "Internal server error"
}

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Product is not found
413The image file is too large (Maximum allowed size is 20Mb)
415Unsupported content-type: expected application/octet-stream
422The uploaded file is not an image
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete product image

Request example

DELETE /api/v3/4870020/products/1234657/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/image?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted images (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
404Product is not found
500Deleting of the image file failed or there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Add image to the product images gallery. Request parameters specify which product should be updated and what title should the uploaded image have. Request body is the image file itself (binary data). Maximum allowed file size is 20Mb.

Request example

POST /api/v3/4870020/products/1234657/gallery?fileName=Extra%20Image&token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/products/123456/gallery?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/products/123456/gallery?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/products/{productId}/gallery?fileName={fileName}token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token
fileNamestringImage title

When uploading an image for a product gallery, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
    "id": 240198557
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal image file ID

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

{
    "errorMessage": "Internal server error"
}

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Product is not found
413The image file is too large (Maximum allowed size is 20Mb)
415Unsupported content-type: expected application/octet-stream
422The uploaded file is not an image
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Request example

DELETE /api/v3/4870020/products/1234657/gallery/1234657345/?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/gallery/{fileId}/?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token
fileIdnumberInternal image file ID

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted images (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
404Product is not found
500Deleting of the image file failed or there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Request example

DELETE /api/v3/4870020/products/39847403/gallery?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

Remove all gallery images attached to the product

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/gallery?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 4
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted gallery images

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
404Product is not found
500Deleting of the files failed or there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Download product file

Download a product file by file ID.

Request example

GET /api/v3/4870020/products/1234657/files/193639?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/products/{productId}/files/{fileId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
fileIdnumberInternal file ID
tokenstringoAuth token

Response

Response is the file in binary format.

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
500Request failed or there was an internal server error
404Product or file is not found

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload product file

Request example

POST /api/v3/4870020/products/1234567/files?token=123456789abcd&fileName=photo+large.psd&description=Item+photo+in+psd+format HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('cool.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/products/123456/files?fileName=cool.jpg&token=abcdefgh123456';

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/products/123456/files?fileName=cool.jpg&token=abcdefgh123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

Uploading a product file (e-goods)

POST https://app.ecwid.com/api/v3/{storeId}/products/{productId}/files?token={token}&fileName={fileName}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token
fileNamestringName of the file that customers will see
descriptionstringA short description of the uploaded file

When uploading an file for a product, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
    "id": 6738222
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal file ID

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

{
    "errorMessage": "Internal server error"
}

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Product is not found
413The file is too large (Maximum allowed size is 100Mb)
415Unsupported content-type: expected application/octet-stream
500Uploading of the file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update product file description

Request example

PUT /api/v3/4870020/products/1234567/files/4838228377?token=123456789abcd&fileName=photo+large.psd&description=Item+photo+in+psd+format HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
    "description": "new description"
}

This request allows to edit the file description that is shown to customer when they purchase the product

PUT https://app.ecwid.com/api/v3/{storeId}/products/{productId}/files/{fileId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
fileIdstringInternal file ID
tokenstringoAuth token

Request body

NameTypeDescription
descriptionstringNew file description

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated entities (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
404Product is not found
415Unsupported content-type: expected application/json or text/json

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete product file

Request example

DELETE /api/v3/4870020/products/1234657/files/193639?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

Delete product’s file (e-goods) by the file ID

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/files/{fileId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
fileIdnumberInternal file ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted files (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
404Product is not found
500Deleting of the file failed or there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete all product files

Request example

DELETE /api/v3/4870020/products/39847403/files?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

Remove all downloadable files attached to the product (e-goods)

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/files?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 3
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted files

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
404Product is not found
500Deleting of the files failed or there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Categories

Get categories

Request

Request example

GET /api/v3/4870020/categories?hidden_categories=true&token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/categories?parent={parent}&hidden_categories={hidden_categories}&offset={offset}&limit={limit}&productIds={productIds}&baseUrl={baseUrl}&cleanUrls={cleanUrls}&token={token}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 100
parentnumberID of the parent category. Set to 0 to get the list of root categories. Leave empty to get all store categories.
hidden_categoriesbooleanBy default, Ecwid returns only enabled categories. Set this parameter to true if you want hidden (disabled) categories to be returned. false is default
productIdsbooleanSet to true if you want the results to contain a list of product IDs assigned to category. false is default
baseUrlstringStorefront URL for Ecwid to use when returning category URLs in the url field. If not specified, Ecwid will use the storefront URL specified in the store settings
cleanUrlsbooleanIf true, Ecwid will return the SEO-friendly clean URL (without hash '#') in the url field. If false, Ecwid will return URL in the old format (with hash '#'). We recommend using true value if merchant’s website supports clean SEO-friendly URL feature

Response

Response example

{
    "total": 2,
    "count": 2,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 9691094,
            "orderBy": 10,
            "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
            "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341234.jpg",
            "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717703.jpg",
            "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124125.jpg",
            "originalImage": {
                "url": "https://app.ecwid.com/default-store/fruit-230-sq.jpg",
                "width": 123,
                "height": 456
            },            
            "name": "Fruit",
            "url": "http://app.ecwid.com/store/4870020#!/Fruit/c/9691094",
            "productCount": 6,
            "enabledProductCount": 5,
            "description": "",
            "enabled": true
        },
        {
            "id": 9691095,
            "orderBy": 20,
            "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690772.jpg",
            "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341254.jpg",
            "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717702.jpg",
            "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124124.jpg",
            "originalImage": {
                "url": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124124.jpg",
                "width": 123,
                "height": 456
            },
            "name": "Vegetables",
            "url": "http://app.ecwid.com/store/4870020#!/Vegetables/c/9691095",
            "productCount": 4,
            "enabledProductCount": 3,
            "enabled": false
        }
    ]
}

Public token request example

GET /api/v3/4870020/categories?hidden_categories=true&token=public_123abcdaASasdASjndasAnsdu HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

Response example

{
    "total": 2,
    "count": 2,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 9691094,
            "orderBy": 10,
            "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
            "thumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/12321312.jpg",
            "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717702.jpg",
            "originalImageUrl": "https://dpbfm6h358sh7.cloudfront.net/1003/1231231231.jpg",
            "originalImage": {
                "url": "https://app.ecwid.com/default-store/fruit-230-sq.jpg",
                "width": 123,
                "height": 456
            },            
            "name": "Fruit",
            "url": "http://app.ecwid.com/store/4870020#!/Fruit/c/9691094",
            "productCount": 6,
            "enabledProductCount": 5,
            "description": "",
            "enabled": true
        },
        {
            "id": 9691095,
            "enabled": false
        }
    ]
}

A JSON object of type ‘SearchResult’ with the following fields:

SearchResult

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe total number of the items returned in this batch
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 100
itemsArrayThe categories list

Category

FieldTypeDescription
idnumberInternal unique category ID
parentIdnumberID of the parent category, if any
orderBynumberSort order of the category in the parent category subcategories list
hdThumbnailUrlstringCategory HD thumbnail URL resized to fit 800x800px
thumbnailUrlstringCategory thumbnail URL. The thumbnail size is specified in the store settings. Resized to fit 400x400px by default
imageUrlstringCategory image URL. A resized original image to fit 1500x1500px
originalImageUrlstringLink to the original (not resized) category image
originalImage<ImageDetails>Details of the category image
namestringCategory name
urlstringURL of the category page in the store. Learn more
productCountnumberNumber of products in the category and its subcategories
enabledProductCountnumberNumber of enabled products in the category (excluding its subcategories)
descriptionstringThe category description in HTML
enabledboolean true if the category is enabled, false otherwise. Use hidden_categories in request to get disabled categories
productIdsArray<number>IDs of products assigned to the category as they appear in Ecwid Control Panel > Catalog > Categories

ImageDetails

FieldTypeDescription
urlstringImage URL
widthintegerImage width
heightintegerImage height

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaningCode (optional)
400Request parameters are malformed
400The cleanUrls value is invalid. It must be either true or falseCLEAN_URLS_PARAMETER_IS_INVALID
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the categories info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Q: How to get URLs for categories?

Direct URL for each category is always available in the url field once you make a request to the Ecwid REST API.

In any Ecwid store there is a storefront URL field, where store owners can specify their storefront location. In case if it’s empty, Ecwid will use their starter site URL to provide category URLs in the REST API and other connected services.

When a store is embedded into multiple websites

For this situation you may need to generate a category feed for each of those websites (building a sitemap, etc.), hence there will be multiple storefront URLs to process. In this case you can use baseUrl request parameter to get a working category URL in a response from the Ecwid REST API.

Let’s see how it works:

If baseUrl request parameter is specified, then the url field will be generated according to that URL as a storefront URL.

Examples

Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com":

  • baseUrl parameter is not set in a request:

Example category URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • baseUrl parameter is set as "https://mycoolstore.com":

Example category URL in the url field will be: "https://mycoolstore.com#!/apple/p/70445445"

As you can see, the category URL in a response from Ecwid API changes based on the value of the baseUrl request parameter. So now you can use it to get category URLs of the same store for any number of storefront URLs.

It is possible to use the baseUrl parameter together with the cleanUrls parameter. See below for more details on the cleanUrls parameter.

Receiving SEO-friendly (clean) URLs from the Ecwid REST API

By default, Ecwid’s category URLs use hash-based format: "https://mdemo.ecwid.com#!/apple/p/70445445". In case if a website supports the SEO-friendly (clean) URLs, you will need to use the cleanUrls request parameter in order to get URLs in that format.

Let’s see how it works:

If cleanUrls request parameter is set to true, then url field will have the SEO-friendly format in the response (clean URL, no hash “#”).

Examples

Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com"

  • cleanUrls parameter is set to false or not set

Example category URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • cleanUrls parameter is set to true

Example category URL in the url field will be: "https://mdemo.ecwid.com/apple-p70445445"

As you can see, the format of a category URL returned from the Ecwid API changes based on the cleanUrls request parameter. So now you can use it to get URLs of any of the two supported URL formats - SEO-friendly (clean) URLs or hash-based URLs.

It is possible to use the cleanUrls parameter together with the baseUrl parameter. See above for more details on the baseUrl parameter.

Get category

Request example

GET /api/v3/4870020/categories/10861116?token=abcdn339900932 HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}?token={token}&baseUrl={baseUrl}&cleanUrls={cleanUrls}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
categoryIdnumberInternal category ID
baseUrlstringStorefront URL for Ecwid to use when returning category URLs in the url field. If not specified, Ecwid will use the storefront URL specified in the store settings
cleanUrlsbooleanIf true, Ecwid will return the SEO-friendly clean URL (without hash '#') in the url field. If false, Ecwid will return URL in the old format (with hash '#'). We recommend using true value if merchant’s website supports clean SEO-friendly URL feature

Response

Response example

{
    "id": 10861116,
    "parentId": 9691094,
    "orderBy": 20,
    "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
    "thumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/12321312.jpg",
    "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717702.jpg",
    "originalImageUrl": "https://dpbfm6h358sh7.cloudfront.net/1003/1231231231.jpg",
    "originalImage": {
        "url": "https://dpbfm6h358sh7.cloudfront.net/1003/1231231231.jpg",
        "width": 123,
        "height": 456
    },
    "name": "Subfruit2",
    "url": "http://app.ecwid.com/store/4870020#!/Subfruit2/c/10861116",
    "productCount": 4,
    "enabledProductCount": 3,
    "description": "<p>arf34</p>",
    "enabled": true
}

Disabled category and public token request example

GET /api/v3/4870020/categories/10861117?token=public_123abcdaASasdASjndasAnsdu HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

Response

{
    "id": 10861117,
    "enabled": false
}

A JSON object of type 'Category’ with the following fields:

Category

FieldTypeDescription
idnumberInternal unique category ID
parentIdnumberID of the parent category, if any
orderBynumberSort order of the category in the parent category subcategories list
hdThumbnailUrlstringCategory HD thumbnail URL resized to fit 800x800px
thumbnailUrlstringCategory thumbnail URL. The thumbnail size is specified in the store settings. Resized to fit 400x400px by default
imageUrlstringCategory image URL. A resized original image to fit 1500x1500px
originalImageUrlstringLink to the original (not resized) category image
originalImage<ImageDetails>Details of the category image
namestringCategory name
urlstringURL of the category page in the store. Learn more
productCountnumberNumber of products in the category and its subcategories
enabledProductCountnumberNumber of enabled products in the category (excluding its subcategories)
descriptionstringThe category description in HTML
enabledboolean true if the category is enabled, false otherwise.
productIdsArray<number>IDs of products assigned to the category as they appear in Ecwid Control Panel > Catalog > Categories

ImageDetails

FieldTypeDescription
urlstringImage URL
widthintegerImage width
heightintegerImage height

Errors

Error response example

HTTP/1.1 400 Wrong numeric parameter 'id' value: not a number or a number out of range
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaningCode (optional)
400Request parameters are malformed
400The cleanUrls value is invalid. It must be either true or falseCLEAN_URLS_PARAMETER_IS_INVALID
404Category is not found
415Unsupported content-type: expected application/json or text/json
500Server error

Q: How to get URLs for categories?

Direct URL for each category is always available in the url field once you make a request to the Ecwid REST API.

In any Ecwid store there is a storefront URL field, where store owners can specify their storefront location. In case if it’s empty, Ecwid will use their starter site URL to provide category URLs in the REST API and other connected services.

When a store is embedded into multiple websites

For this situation you may need to generate a category feed for each of those websites (building a sitemap, etc.), hence there will be multiple storefront URLs to process. In this case you can use baseUrl request parameter to get a working category URL in a response from the Ecwid REST API.

Let’s see how it works:

If baseUrl request parameter is specified, then the url field will be generated according to that URL as a storefront URL.

Examples

Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com":

  • baseUrl parameter is not set in a request:

Example category URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • baseUrl parameter is set as "https://mycoolstore.com":

Example category URL in the url field will be: "https://mycoolstore.com#!/apple/p/70445445"

As you can see, the category URL in a response from Ecwid API changes based on the value of the baseUrl request parameter. So now you can use it to get category URLs of the same store for any number of storefront URLs.

It is possible to use the baseUrl parameter together with the cleanUrls parameter. See below for more details on the cleanUrls parameter.

Receiving SEO-friendly (clean) URLs from the Ecwid REST API

By default, Ecwid’s category URLs use hash-based format: "https://mdemo.ecwid.com#!/apple/p/70445445". In case if a website supports the SEO-friendly (clean) URLs, you will need to use the cleanUrls request parameter in order to get URLs in that format.

Let’s see how it works:

If cleanUrls request parameter is set to true, then url field will have the SEO-friendly format in the response (clean URL, no hash “#”).

Examples

Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com"

  • cleanUrls parameter is set to false or not set

Example category URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • cleanUrls parameter is set to true

Example category URL in the url field will be: "https://mdemo.ecwid.com/apple-p70445445"

As you can see, the format of a category URL returned from the Ecwid API changes based on the cleanUrls request parameter. So now you can use it to get URLs of any of the two supported URL formats - SEO-friendly (clean) URLs or hash-based URLs.

It is possible to use the cleanUrls parameter together with the baseUrl parameter. See above for more details on the baseUrl parameter.

Add new category

Request

Request body

POST /api/v3/4870020/categories?token=alads043043lk0ds0 HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
    "name": "New Cool Category",
    "description": "Hey, this is my <b>new</b> category!",
    "enabled": true,
    "orderBy": 10,
    "parentId": 9691094
}

POST https://app.ecwid.com/api/v3/{storeId}/categories?token={token}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'Category’ with the following fields:

Category

FieldTypeDescription
namestringCategory name
parentIdnumberID of the parent category. Omit this field to add root category
orderBynumberSort order of the category in the parent category subcategories list
descriptionstringThe category description in HTML
enabledboolean true to make category enabled, false otherwise. true is default
productIdsArray<number>IDs of the products to assign to the category

Response

Response example

{
    "id": 10869029
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberID of the created category

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Malformed request parameters
402The merchant plan category limit is reached
404The parent category or one of the assigned products is not found
409Data validation error: the category name or description exceed the max allowed length of characters
415Unsupported content-type: expected application/json or text/json
449Store catalog cannot be modified at the moment because import is in progress. Retry later
500Server error

Update category

Request

Request body

PUT /api/v3/4870020/categories/10869029?token=34534509340sdsreoiweurt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
  "name": "Updated name",
  "description": "Updated <b>description</b>",
  "productIds": [
    37208339,
    37208345
  ]
}

PUT https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}?token={token}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
categoryIdnumberCategory internal ID

Request body

A JSON object of type 'Category’ with the following fields:

Category

FieldTypeDescription
namestringCategory name
parentIdnumberID of the parent category
orderBynumberSort order of the category in the parent category subcategories list
descriptionstringThe category description in HTML
enabledboolean true to make category enabled, false to disable it. true is default
productIdsArray<number>IDs of the products to assign to the category

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated categories (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Malformed request parameters
400Category name must not be empty
404The parent category or one of the assigned products is not found
409There was a conflict modifying the store (updating a category while it’s being edited elsewhere). Retry later.
415Unsupported content-type: expected application/json or text/json
449Store catalog cannot be modified at the moment because import is in progress. Retry later.
500Server error

Delete a category

Request example

DELETE /api/v3/4870020/categories/10861116?token=abcdn339900932 HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}?token={token}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
categoryIdnumberCategory internal ID

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted categories (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 400 Bad request
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Malformed request parameters
415Unsupported content-type: expected application/json or text/json
449Store catalog cannot be modified at the moment because import is in progress. Retry later.
500Server error

Upload category image

Upload category image: if the category already has an image attached, the uploaded image will replace the existing one. Maximum allowed file size is 20Mb.

Request example

POST /api/v3/4870020/categories/1234657/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/categories/123456/image?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/categories/123456/image?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}/image?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
categoryIdnumberCategory ID
tokenstringoAuth token

When uploading an image for a category, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
    "id": 240198557
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal image ID

Errors

Error response example

HTTP/1.1 422 Uploaded file cannot be processed. Please make sure you upload an image file

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
404Category is not found
413The image file is too large (Maximum allowed size is 20Mb)
415Unsupported content-type: expected application/octet-stream
422The uploaded file is not an image
500Uploading of the image file failed or there was an internal server error while processing a file. On of possible reasons is image

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete category image

Request example

DELETE /api/v3/4870020/categories/1234657/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}/image?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
categoryIdnumberCategory ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted images (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
404Category is not found
500Deleting of the image file failed or there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Product combinations

Get all product combinations

Request example

GET /api/v3/4870020/products/8383892837/combinations?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID

Response

Response example (JSON)

[
  {
    "id":7084071,
    "combinationNumber":6,
    "options":[
      {
        "name":"Size",
        "value":"Large"
      },
      {
        "name":"Color",
        "value":"White"
      }
    ],
    "sku":"000076",
    "smallThumbnailUrl":"http://images-cdn.ecwid.com/images/4870020/249912079.jpg",
    "hdThumbnailUrl": "https://images-cdn.ecwid.com/images/4870020/397690841.jpg",
    "thumbnailUrl":"http://images-cdn.ecwid.com/images/4870020/249912077.jpg",
    "imageUrl":"http://images-cdn.ecwid.com/images/4870020/249912061.jpg",
    "originalImageUrl":"http://images-cdn.ecwid.com/images/4870020/249912061.jpg",
    "quantity":21,
    "unlimited":false,
    "price":1.45,
    "wholesalePrices":[
      {
        "quantity":10,
        "price":1.05
      }
    ],
    "warningLimit":1
  },
  {
    "id":7084072,
    "combinationNumber":5,
    "options":[
      {
        "name":"Color",
        "value":"Red"
      },
      {
        "name":"Size",
        "value":"Large"
      }
    ],
    "sku":"000075",
    "quantity":0,
    "unlimited":false,
    "warningLimit":0
  },
  {
    "id":7084075,
    "combinationNumber":2,
    "options":[
      {
        "name":"Size",
        "value":"Small"
      },
      {
        "name":"Color",
        "value":"White"
      }
    ],
    "sku":"000072",
    "smallThumbnailUrl":"http://images-cdn.ecwid.com/images/4870020/249912078.jpg",
    "hdThumbnailUrl": "https://images-cdn.ecwid.com/images/4870020/397690841.jpg",
    "thumbnailUrl":"http://images-cdn.ecwid.com/images/4870020/249912076.jpg",
    "imageUrl":"http://images-cdn.ecwid.com/images/4870020/249912060.jpg",
    "originalImageUrl":"http://images-cdn.ecwid.com/images/4870020/249912060.jpg",
    "quantity":62,
    "unlimited":false,
    "price":1.45,
    "wholesalePrices":[
      {
        "quantity":10,
        "price":1.35
      },
      {
        "quantity":20,
        "price":1.25
      }
    ],
    "warningLimit":10
  },
  {
    "id":7084076,
    "combinationNumber":1,
    "options":[
      {
        "name":"Size",
        "value":"Small"
      },
      {
        "name":"Color",
        "value":"Red"
      }
    ],
    "sku":"000071",
    "quantity":61,
    "unlimited":false,
    "warningLimit":0
  }
]

An array of JSON objects of type ‘Combination’ with the following fields:

Combination

FieldTypeDescription
idnumberCombination ID
combinationNumbernumberCombination # number, which is displayed in the combinations table in Control panel
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
thumbnailUrlstringURL of the product combination thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product combination image resized to fit 1500x1500px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product combination thumbnail resized to fit 160x160px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct combination HD thumbnail URL resized to fit 800x800px. Omitted if the combination inherits the base product’s image.
originalImageUrlstringURL of the original not resized product combination image. Omitted if the combination inherits the base product’s image.
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedboolean true if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination inherits the base product’s settings.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

WholesalePrice

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

Errors

Error response example

HTTP/1.1 400 Wrong numeric parameter 'id' value: not a number or a number out of range
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The “Product Combinations” feature are not available on the merchant plan
415Unsupported content-type: expected application/json or text/json
500Cannot get combinations because of an error on the server

Get product combination

Request example

GET /api/v3/4870020/products/8383892837/combinations/772828388?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID
combinationIdnumberInternal combination ID

Response

Response example (JSON)

{
    "id": 7084075,
    "combinationNumber": 2,
    "options": [
        {
            "name": "Size",
            "value": "Small"
        },
        {
            "name": "Color",
            "value": "White"
        }
    ],
    "sku": "000072",
    "smallThumbnailUrl": "http://images-cdn.ecwid.com/images/4870020/249919682.jpg",
    "hdThumbnailUrl": "https://images-cdn.ecwid.com/images/4870020/397690841.jpg",
    "thumbnailUrl": "http://images-cdn.ecwid.com/images/4870020/249919680.jpg",
    "imageUrl": "http://images-cdn.ecwid.com/images/4870020/249912060.jpg",
    "originalImageUrl": "http://images-cdn.ecwid.com/images/4870020/249912060.jpg",
    "quantity": 62,
    "unlimited": false,
    "price": 1.45,
    "wholesalePrices": [
        {
            "quantity": 10,
            "price": 1.35
        },
        {
            "quantity": 20,
            "price": 1.25
        }
    ],
    "warningLimit": 10
}

An array of JSON objects of type 'Combination’ with the following fields:

Combination

FieldTypeDescription
idnumberCombination ID
combinationNumbernumberCombination # number, which is displayed in the combinations table in Control panel
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
thumbnailUrlstringURL of the product combination thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product combination image resized to fit 1500x1500px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product combination thumbnail resized to fit 160x160px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct combination HD thumbnail URL resized to fit 800x800px. Omitted if the combination inherits the base product’s image.
originalImageUrlstringURL of the original not resized product combination image. Omitted if the combination inherits the base product’s image.
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedboolean true if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination inherits the base product’s settings.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

WholesalePrice

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The “Product Combinations” feature are not available on the merchant plan
404The combination is not found
415Unsupported content-type: expected application/json or text/json
500Cannot get the combination because of an error on the server

Create product combination

You can create a new product combination using this method. If the options you specify in request don’t exist, they will be created automatically with the type of dropdown. If you want to create options explicitly, use the Update product call to create them.

Request example

POST /api/v3/4870020/products/8383892837/combinations?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8

{
    "options": [
        {
            "name": "Size",
            "value": "L"
        },
        {
            "name": "Color",
            "value": "Red"
        }
    ],
    "price": 10,
    "quantity": 4,
    "weight": 0.5,
    "sku": "combination-sku"
}

POST https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID

Request body

A JSON object of type 'Combination’ with the following fields:

Combination

FieldTypeDescription
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedboolean true if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination inherits the base product’s settings.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

WholesalePrice

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

Response

Response example

{
    "id": 397662764
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberID of the created combination

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The “Product Combinations” feature are not available on the merchant plan
404The product is not found
409The specified sku or options variation already exists
415Unsupported content-type: expected application/json or text/json
500Cannot get the combination because of an error on the server

Update product combination

Request example

PUT /api/v3/4870020/products/8383892837/combinations/772828388?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8

{
    "price": 10,
    "quantity": 4,
    "weight": 0.5,
    "sku": "combination-new-sku"
}

PUT https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID
combinationIdnumberInternal combination ID

Request body

A JSON object of type 'Combination’ with the following fields:

Combination

FieldTypeDescription
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedboolean true if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination inherits the base product’s settings.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

WholesalePrice

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated combinations (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The “Product Combinations” feature are not available on the merchant plan
404The product or combination is not found
409The specified sku or options variation already exists
415Unsupported content-type: expected application/json or text/json
500Cannot get the combination because of an error on the server

Delete product combination

Request example

DELETE /api/v3/4870020/products/8383892837/combinations/772828388?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID
combinationIdnumberInternal combination ID

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted combinations (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The “Product Combinations” feature is not available on the merchant plan
404The combination is not found
500Cannot remove the combination because of an error on the server

Delete all product combinations

Request example

DELETE /api/v3/4870020/products/8383892837/combinations?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID

Response

Response example

{
    "deleteCount": 4
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted combinations

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The “Product Combinations” feature is not available on the merchant plan
500Cannot delete combinations because of an error on the server

Adjust combination inventory

Request example

PUT /api/v3/4870020/products/8383892837/combinations/772828388/inventory?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
    "quantityDelta": -10
}

When your integration changes in stock quantity of product combination in a store pretty often, it becomes harder and harder to keep track of how many items are actually in stock. For example, when at one point of time you have 3 items in stock and 5 in the very next second, then using the specific values can result in incorrect stock quantity.

This method solves this very problem: you can increase or decrease the product combination’s stock quantity by a delta quantity. For example, if you need to decrease quantity by 10 items, you can use this method.

This method is also available for products.

PUT https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}/inventory?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
combinationIdnumberCombination ID
tokenstringoAuth token

Request body

A JSON object of type 'Inventory’ with the following fields:

Inventory

FieldTypeDescription
quantityDeltanumberDelta value used to update product quantity. Negative value will decrease quantity, positive one will increase it.

Response

Response example (JSON)

{
  "updateCount": 1
}

A JSON object of type 'InventoryAdjustmentStatus’ with the following fields:

InventoryAdjustmentStatus

FieldTypeDescription
updateCountnumberThe number of updated products (1 or 0 depending on whether the update was successful)
warningstringInventory update warning(optional). For example, the warning will display if the stock became negative

Errors

HTTP/1.1 400 Bad Request
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402This functionality is not available on this plan
404Product not found
415Unsupported content-type: expected application/json or text/json
500Could not process the request, internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload combination image

Request example

POST /api/v3/4870020/products/1234657/combinations/463737373/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/products/123456/combinations/1233541/image?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/products/123456/combinations/1233541/image?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}/image?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token
combinationIdnumberInternal combination ID

When uploading an image for a combination, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
    "id": 240198557
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal image ID

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

{
    "errorMessage": "Internal server error"
}

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Product or combination in request are not found
413The image file is too large (Maximum allowed file size is 20Mb)
422The uploaded file is not an image
415Unsupported content-type: expected application/octet-stream
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete combination image

Request example

DELETE /api/v3/4870020/products/1234657/combinations/463737373/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}/image?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token
combinationIdnumberInternal combination ID

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted images (1 if the image has been removed, 0 otherwise)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, a JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The Product combinations are not available on the merchant plan
404Product or combination in request are not found
500Request failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Product types

Product types (or product classes) are groups of products which share the same attributes. Product attributes contain additional product information, e.g. ISBN, UPC, Brand, which is displayed in storefront and included in product feeds when exporting to marketplaces like Google Shopping, eBay, Amazon ads etc. Learn more about product types and attributes in Ecwid Help center.

Get product types

Request

Request example

GET /api/v3/4870020/classes?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/classes?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Response

Response example (JSON)

[
  {
    "id":0,
    "attributes":[
      {
        "id":5029057,
        "name":"Brand",
        "type":"BRAND",
        "show":"DESCR"
      },
      {
        "id":5029058,
        "name":"UPC",
        "type":"UPC",
        "show":"DESCR"
      }
    ]
  },
  {
    "id":4208002,
    "name":"Body Weight Scale Accessories",
    "googleTaxonomy":"Health & Beauty > Health Care > Biometric Monitor Accessories > Body Weight Scale Accessories",
    "attributes":[
      {
        "id":5508061,
        "name":"UPC",
        "type":"UPC",
        "show":"DESCR"
      },
      {
        "id":5508062,
        "name":"Brand",
        "type":"BRAND",
        "show":"DESCR"
      }
    ]
  }
]

A JSON array of objects of type ‘ProductClass’ with the following fields:

ProductClass

FieldTypeDescription
idnumberProduct type (class) internal unique ID. Class with ID 0 is the default 'General’ type assigned to all products by default
namestringProduct type name. Empty for the “General” type
googleTaxonomystringGoogle taxonomy associated with this type
attributesArray<Attribute>Product type attributes

Attribute

FieldTypeDescription
idnumberAttribute internal unique ID
namestringAttribute title
typestringAttribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: CUSTOM, UPC, BRAND, GENDER, AGE_GROUP, COLOR, SIZE, PRICE_PER_UNIT, UNITS_IN_PRODUCT
showstringDefines how and where to display the product attribute value: NOTSHOW, DESCR, PRICE

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the product type info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get product type

Request

Request example

GET /api/v3/4870020/classes/4208002?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/classes/{classId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
classIdnumberProduct type internal ID

Response

Response example (JSON)

  {
    "id":4208002,
    "name":"Body Weight Scale Accessories",
    "googleTaxonomy":"Health & Beauty > Health Care > Biometric Monitor Accessories > Body Weight Scale Accessories",
    "attributes":[
      {
        "id":5508061,
        "name":"UPC",
        "type":"UPC",
        "show":"DESCR"
      },
      {
        "id":5508062,
        "name":"Brand",
        "type":"BRAND",
        "show":"DESCR"
      }
    ]
  }

A JSON object of type 'ProductClass’ with the following fields:

ProductClass

FieldTypeDescription
idnumberProduct class internal unique ID. Class with ID 0 is the default 'General’ type assigned to all products by default
namestringProduct type name. Empty for the “General” type
googleTaxonomystringGoogle taxonomy associated with this type
attributesArray<Attribute>Product type attributes

Attribute

FieldTypeDescription
idnumberAttribute internal unique ID
namestringAttribute title
typestringAttribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: CUSTOM, UPC, BRAND, GENDER, AGE_GROUP, COLOR, SIZE, PRICE_PER_UNIT, UNITS_IN_PRODUCT
showstringDefines how and where to display the product attribute value: NOTSHOW, DESCR, PRICE

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
404Product type is not found
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the product type info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update product type

Request

Request example

PUT /api/v3/4870020/classes/4208002?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

{
    "name": "New Class Name",
    "attributes": [
        {
            name: "New attribute name",
            type: "CUSTOM",
            show: "DESCR"            
        }
    ]
}

PUT https://app.ecwid.com/api/v3/{storeId}/classes/{classId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
classIdnumberProduct type internal ID

Request body

A JSON object of type 'ProductClass’ with the following fields:

ProductClass

FieldTypeDescription
namestringProduct type name
attributesArray<Attribute>Product type attributes

Attribute

FieldTypeDescription
idnumberAttribute internal unique ID (leave empty when adding a new attribute)
namestringAttribute title
typestringAttribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: CUSTOM, UPC, BRAND, GENDER, AGE_GROUP, COLOR, SIZE, PRICE_PER_UNIT, UNITS_IN_PRODUCT
showstringDefines how and where to display the product attribute value: NOTSHOW, DESCR, PRICE

Response

Response example (JSON)

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated types (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, a JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
409The type/class with the given name already exists
415Unsupported content-type: expected application/json or text/json
500The request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Create product type

Request

Request example

POST /api/v3/4870020/classes?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

{
"name": "T-Shirts",
    "attributes": [
        {
            "name": "Gender",
            "type": "CUSTOM",
            "show": "DESCR"
        },
        {
            "name": "Age group",
            "type": "CUSTOM",
            "show": "DESCR"
        },
        {
            "name": "Color",
            "type": "CUSTOM",
            "show": "DESCR"
        },
        {
            "name": "Size",
            "type": "CUSTOM",
            "show": "DESCR"
        }
      ]
}

POST https://app.ecwid.com/api/v3/{storeId}/classes?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'ProductClass’ with the following fields:

ProductClass

FieldTypeDescription
namestringProduct type name. Ecwid will try to find a Google taxonomy that matches the name you submit here. If it finds, the taxonomy will be assigned to the new type.
attributesArray<Attribute>Product type attributes

Attribute

FieldTypeDescription
namestringAttribute title
typestringAttribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: CUSTOM, UPC, BRAND, GENDER, AGE_GROUP, COLOR, SIZE, PRICE_PER_UNIT, UNITS_IN_PRODUCT
showstringDefines how and where to display the product attribute value: NOTSHOW, DESCR, PRICE

Response

Response example (JSON)

{
    "id": 4528008
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberThe internal ID of the just created product type

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, a JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
409The type/class with the given name already exists
415Unsupported content-type: expected application/json or text/json
500The request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete product type

This request removes product type and its assigned attributes. The products that belong to this type will not be removed. They will be re-assigned to the General type

Request

Request example

DELETE /api/v3/4870020/classes/4208002?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/classes/{classId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
classIdnumberProduct type internal ID

Response

Response example (JSON)

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted types (1 or 0 depending on whether the request was successful). It returns 0 when the type with the given ID is not found

Errors

Error response example

HTTP/1.1 400 Wrong numeric parameter 'id' value: not a number or a number out of range
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
500Cannot retrieve the product type info because of an error on the server

Orders

Search orders

Request example

GET /api/v3/4870020/orders?customer=johnsmith@example.com&paymentStatus=PAID,AWAITING_PAYMENT&token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/orders?keywords={keywords}&totalFrom={totalFrom}&totalTo={totalTo}&createdFrom={createdFrom}&createdTo={createdTo}&updatedFrom={updatedFrom}&updatedTo={updatedTo}&couponCode={couponCode}&orderNumber={orderNumber}&vendorOrderNumber={vendorOrderNumber}&customer={customer}&paymentMethod={paymentMethod}&shippingMethod={shippingMethod}&paymentStatus={paymentStatus}&fulfillmentStatus={fulfillmentStatus}&offset={offset}&limit={limit}&token={token}

Q: How to get info about abandoned sales?

To get abandoned sale information, specify INCOMPLETE for paymentStatus filter when searching for orders.

Coming soon: Abandoned sales have a unique cart identification in orderNumber field. Because of that, the orderNumber field in return from the Ecwid REST API will be of type string and will look like this: "551c5edd-5fae-40c1-99a9-25095df20e4f"

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
keywordsstringSearch term. Ecwid will look for this term in order number, ordered items and customer details.
couponCodenumberThe code of coupon applied to order
totalFromnumberMinimum product price
totalTonumberMaximum product price
orderNumbernumberOrder number
vendorOrderNumberstringOrder number with prefix/suffix defined by admin
customerstringCustomer search term. Searches for customer details in order, except for customerId
createdFromstringOrder placement date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
Examples:
  • 1447804800
  • 2015-04-22 18:48:38 -0500
  • 2015-04-22 (this is 2015-04-22 00:00:00 UTC)
createdTostringOrder placement date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedFromstringOrder last update date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedTostringOrder last update date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
paymentMethodstringPayment method used by customer
shippingMethodstringShipping method chosen by customer
paymentStatusstringComma separated list of order payment statuses to search. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
fulfillmentStatusstringComma separated list of order fulfilment statuses to search. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP

Response

Response example (JSON)

{
    "total": 1,
    "count": 1,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            // Basic information
            "vendorOrderNumber": "20",
            "orderNumber": 20,
            "tax": 1.79,
            "subtotal": 29.95,
            "total": 37.39,
            "usdTotal": 37.39,
            "paymentMethod": "Purchase order",
            "paymentStatus": "PAID",
            "fulfillmentStatus": "AWAITING_PROCESSING",

            // Additional information
            "refererUrl": "http://mysuperstore.ecwid.com/",
            "globalReferer": "",
            "createDate": "2014-09-20 19:59:43 +0000",
            "updateDate": "2014-09-21 00:00:12 +0000",
            "createTimestamp": 1427268654,
            "updateTimestamp": 1427272209,
            "hidden": false,
            "orderComments": "Test order comments",
            "privateAdminNotes": "Must be delivered till Sunday.",

            // Basic customer information
            "email": "johnsmith@example.com",
            "ipAddress": "83.217.8.241",
            "customerId": 15319410,
            "customerGroupId": 12345,
            "customerGroup": "Gold",
            "customerTaxExempt": false,
            "customerTaxId": "",
            "customerTaxIdValid": false,
            "reversedTaxApplied": false,

            // Discounts in order
            "membershipBasedDiscount": 0,
            "totalAndMembershipBasedDiscount": 2.85,
            "couponDiscount": 1.5,
            "discount": 2.85,
            "volumeDiscount": 0,
            "discountCoupon": {
                "name": "Coupon # 3",
                "code": "5PERCENTOFF",
                "discountType": "PERCENT",
                "status": "ACTIVE",
                "discount": 5,
                "launchDate": "2014-06-06 00:00:00 +0000",
                "usesLimit": "UNLIMITED",
                "repeatCustomerOnly": false,
                "creationDate": "2014-09-20 19:58:49 +0000",
                "orderCount": 0
            },
            "discountInfo": [
                {
                    "value": 10,
                    "type": "PERCENT",
                    "base": "ON_TOTAL_AND_MEMBERSHIP",
                    "orderTotal": 15
                },
                {
                    "value": 2,
                    "type": "ABSOLUTE",
                    "base": "CUSTOM",
                    "description": "Buy more than 3 cherries and get $2 off!"
                }
            ],

            // Order items details
            "items": [
                {
                    "id": 40989227,
                    "productId": 37208342,
                    "categoryId": 9691094,
                    "price": 5.99,
                    "productPrice": 5.99,
                    "weight": 0.32,
                    "sku": "00004",
                    "quantity": 5,
                    "shortDescription": "Cherry\nThe word cherry refers to a fleshy fruit (drupe) that contains a single stony seed. The cherry belongs to the fa...",
                    "tax": 1.79,
                    "shipping": 10,
                    "quantityInStock": 1981,
                    "name": "Cherry",
                    "isShippingRequired": true,
                    "trackQuantity": true,
                    "fixedShippingRateOnly": false,
                    "imageUrl": "http://app.ecwid.com/default-store/00006-sq.jpg",
                    "fixedShippingRate": 1,
                    "digital": true,
                    "productAvailable": true,
                    "couponApplied": false,
                    "files": [
                        {
                            "productFileId": 7215101,
                            "maxDownloads": 0,
                            "remainingDownloads": 0,
                            "expire": "2014-10-26 20:34:34 +0000",
                            "name": "myfile.jpg",
                            "description": "Sunflower",
                            "size": 54492,
                            "adminUrl": "https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215101?token=123123123",
                            "customerUrl": "http://mysuperstore.ecwid.com/download/4870020/a2678e7d1d1c557c804c37e4/myfile.jpg"
                        }
                    ],
                    "selectedOptions": [
                        {
                            "name": "Size",
                            "value": "Big",
                            "valuesArray" : [
                              "Big"
                            ],
                            "type": "CHOICE"
                        },
                        {
                            "name": "Attach a file",
                            "type": "FILES",
                            "files": [
                                {
                                    "id": 5973037,
                                    "name": "makfruit_ava_sunnyflower_200_200.jpg",
                                    "size": 54492,
                                    "url": "https://app.ecwid.com/orderfile/4870020/5973037/54492/makfruit_ava_sunnyflower_200_200.jpg"
                                }
                            ]
                        },
                        {
                            "name": "Choose date",
                            "value": "2014-09-10",
                            "type": "DATE"
                        },
                        {
                            "name": "Any text",
                            "value": "Test text",
                            "type": "TEXT"
                        }
                    ],
                    "taxes": [
                        {
                            "name": "Tax X",
                            "value": 7,
                            "total": 1.79,
                            "taxOnDiscountedSubtotal": 1.79,
                            "taxOnShipping": 0
                        }
                    ],
                    "productDimensions": {
                        "length": 34,
                        "width": 3,
                        "height": 22
                    }
                }
            ],

            // Customer addresses
            "billingPerson": {
                "name": "John Smith",
                "companyName": "Unreal Company",
                "street": "W 3d st",
                "city": "New York",
                "countryCode": "US",
                "countryName": "United States",
                "postalCode": "10001",
                "stateOrProvinceCode": "NY",
                "stateOrProvinceName": "New York",
                "phone": "+1234567890"
            },
            "shippingPerson": {
                "name": "John Smith",
                "companyName": "Unreal Company",
                "street": "W 3d st",
                "city": "New York",
                "countryCode": "US",
                "countryName": "United States",
                "postalCode": "10001",
                "stateOrProvinceCode": "NY",
                "stateOrProvinceName": "New York",
                "phone": "+1234567890"
            },

            // Shipping information
            "shippingOption": {
                "shippingMethodName": "2nd day delivery",
                "shippingRate": 10,
                "estimatedTransitTime": "5",
                "isPickup": false,
                "pickupInstruction": ""
            },
            "handlingFee": {
                "name": "Wrapping",
                "value": 2,
                "description": "Silk paper wrapping"
            },

            // Other information
            "additionalInfo": {},
            "paymentParams": {
                "Company name": "Unreal Company",
                "Job position": "Manager",
                "PO number": "123abcd",
                "Buyer's full name": "John Smith"
            }
        }
    ]
}

A JSON object of type ‘SearchResult’ with the following fields:

SearchResult

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe total number of the items returned in this batch
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
itemsArray<OrderEntry>The items list

OrderEntry

FieldTypeDescription
orderNumbernumber/stringUnique order number without prefixes/suffixes, e.g. 34. COMING SOON: For completed orders orderNumber will work as described earlier. For abandoned sales i.e. the paymentStatus is INCOMPLETE, orderNumber will be a unique cart ID of type string and it will look like this: "551c5edd-5fae-40c1-99a9-25095df20e4f"
vendorOrderNumberstringOrder number with prefix and suffix defined by admin, e.g. ABC34-q. COMING SOON: For completed orders, vendorOrderNumber will work as described earlier. For abandoned sales i.e. the paymentStatus is INCOMPLETE, vendorOrderNumber will be a unique cart ID and will look like this: "551c5edd-5fae-40c1-99a9-25095df20e4f"
subtotalnumberOrder subtotal
totalnumberOrder total cost
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total
customerTaxExemptboolean true if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidboolean true if customer tax ID is valid, false otherwise
reversedTaxAppliedboolean true if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
ipAddressstringCustomer IP
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringOrder comments
couponDiscountnumberDiscount applied to order using a coupon
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
discountnumberThe sum of all applied discounts except for the coupon discount. To get the total order discount, take the sum of couponDiscount and discount field values
membershipBasedDiscountnumberSum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscountnumberThe sum of discount based on subtotal AND customer group. Is included into the discount field
discountCoupon<DiscountCouponInfo>Information about applied coupon
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unsfinished orders only.
usdTotalnumberOrder total in USD
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
updateDatedateThe date/time of the last order change, e.g 2014-06-06 18:57:19 +0000
createTimestampnumberThe date of order placement in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberThe date of the last order change in UNIX Timestamp format, e.g 1427268654
customerGroupIdnumberCustomer group ID
customerGroupstringThe name of group (membership) the customer belongs to
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn’t belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredboolean true/false: shows whether the item requires shipping
trackQuantityboolean true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlyboolean true/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalboolean true/false: shows whether the item has downloadable files attached
productAvailableboolean true/false: shows whether the product is available in the store
couponAppliedboolean true/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item
filesArray<OrderItemProductFile>Files attached to the order item
productDimensions<ProductDimensions>Product dimensions info

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping

OrderItemProductFile

FieldTypeDescription
productFileIdnumberInternal unique file ID
maxDownloadsnumberMax allowed number of file downloads. See E-goods article in Ecwid Help center for the details
remainingDownloadsnumberRemaining number of download attempts
expirestringDate/time of the customer download link expiration
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringLink to the file. Be careful: the link contains the API access token. Make sure you do not display the link as is in your application and not give it to a customer.
customerUrlstringFile download link that is sent to the customer when the order is paid

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered option value(s) as a string. For the CHOICES type, provides a string with all chosen values (comma-separated). You can use this to simply print out all selected values.
valuesArrayArraySelected option values as an array. For the CHOICES type, provides an array with the chosen values so you can iterate through them in your app.
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

OrderItemOptionFile

FieldTypeDescription
idnumberFile ID
namestringFile name
sizenumberFile size in bytes
urlstringFile URL

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by ’\n’
citystringCity
countryCodestringTwo-letter country code
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name
phonestringPhone number

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringShipping carrier name, e.g. USPS
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Possible formats: number “5”, several days estimate “4-9”
isPickupboolean true if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
order_totalnumberMinimum order subtotal the discount applies to
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get order details

Request example

GET /api/v3/4870020/orders/20?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber

Response

Response example (JSON)

{
    // Basic information
    "vendorOrderNumber": "20",
    "orderNumber": 20,
    "tax": 1.79,
    "subtotal": 29.95,
    "total": 37.39,
    "usdTotal": 37.39,
    "paymentMethod": "Purchase order",
    "paymentStatus": "PAID",
    "fulfillmentStatus": "AWAITING_PROCESSING",

    // Additional information
    "refererUrl": "http://mysuperstore.ecwid.com/",
    "globalReferer": "",
    "createDate": "2014-09-20 19:59:43 +0000",
    "updateDate": "2014-09-21 00:00:12 +0000",
    "createTimestamp": 1427268654,
    "updateTimestamp": 1427272209,
    "hidden": false,
    "orderComments": "Test order comments",
    "privateAdminNotes": "Must be delivered till Sunday.",

    // Basic customer information
    "email": "johnsmith@example.com",
    "ipAddress": "83.217.8.241",
    "customerId": 15319410,
    "customerGroupId": 12345,
    "customerGroup": "Gold",
    "customerTaxExempt": false,
    "customerTaxId": "",
    "customerTaxIdValid": false,
    "reversedTaxApplied": false,    

    // Discounts in order
    "membershipBasedDiscount": 0,
    "totalAndMembershipBasedDiscount": 2.85,
    "couponDiscount": 1.5,
    "discount": 2.85,
    "volumeDiscount": 0,
    "discountCoupon": {
        "name": "Coupon # 3",
        "code": "5PERCENTOFF",
        "discountType": "PERCENT",
        "status": "ACTIVE",
        "discount": 5,
        "launchDate": "2014-06-06 00:00:00 +0000",
        "usesLimit": "UNLIMITED",
        "repeatCustomerOnly": false,
        "creationDate": "2014-09-20 19:58:49 +0000",
        "orderCount": 0
    },
    "discountInfo": [
        {
            "value": 10,
            "type": "PERCENT",
            "base": "ON_TOTAL_AND_MEMBERSHIP",
            "orderTotal": 15
        }
    ],

    // Order items details
    "items": [
        {
            "id": 40989227,
            "productId": 37208342,
            "categoryId": 9691094,
            "price": 5.99,
            "productPrice": 5.99,
            "weight": 0.32,
            "sku": "00004",
            "quantity": 5,
            "shortDescription": "Cherry\nThe word cherry refers to a fleshy fruit (drupe) that contains a single stony seed. The cherry belongs to the fa...",
            "tax": 1.79,
            "shipping": 10,
            "quantityInStock": 1981,
            "name": "Cherry",
            "isShippingRequired": true,
            "trackQuantity": true,
            "fixedShippingRateOnly": false,
            "imageUrl": "http://app.ecwid.com/default-store/00006-sq.jpg",
            "fixedShippingRate": 1,
            "digital": true,
            "productAvailable": true,
            "couponApplied": false,
            "files": [
                {
                    "productFileId": 7215101,
                    "maxDownloads": 0,
                    "remainingDownloads": 0,
                    "expire": "2014-10-26 20:34:34 +0000",
                    "name": "myfile.jpg",
                    "description": "Sunflower",
                    "size": 54492,
                    "adminUrl": "https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215101?token=123123123",
                    "customerUrl": "http://mysuperstore.ecwid.com/download/4870020/a2678e7d1d1c557c804c37e4/myfile.jpg"
                }
            ],
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Big",
                    "valuesArray" : [
                      "Big"
                    ],
                    "type": "CHOICE"
                },
                {
                    "name": "Attach a file",
                    "type": "FILES",
                    "files": [
                        {
                            "id": 5973037,
                            "name": "makfruit_ava_sunnyflower_200_200.jpg",
                            "size": 54492,
                            "url": "https://app.ecwid.com/orderfile/4870020/5973037/54492/makfruit_ava_sunnyflower_200_200.jpg"
                        }
                    ]
                },
                {
                    "name": "Choose date",
                    "value": "2014-09-10",
                    "type": "DATE"
                },
                {
                    "name": "Any text",
                    "value": "Test text",
                    "type": "TEXT"
                }
            ],
            "taxes": [
                {
                    "name": "Tax X",
                    "value": 7,
                    "total": 1.79,
                    "taxOnDiscountedSubtotal": 1.79,
                    "taxOnShipping": 0
                }
            ],
            "productDimensions": {
                "length": 34,
                "width": 3,
                "height": 22
            }
        }
    ],

    // Customer addresses
    "billingPerson": {
        "name": "John Smith",
        "companyName": "Unreal Company",
        "street": "W 3d st",
        "city": "New York",
        "countryCode": "US",
        "countryName": "United States",
        "postalCode": "10001",
        "stateOrProvinceCode": "NY",
        "stateOrProvinceName": "New York",
        "phone": "+1234567890"
    },
    "shippingPerson": {
        "name": "John Smith",
        "companyName": "Unreal Company",
        "street": "W 3d st",
        "city": "New York",
        "countryCode": "US",
        "countryName": "United States",
        "postalCode": "10001",
        "stateOrProvinceCode": "NY",
        "stateOrProvinceName": "New York",
        "phone": "+1234567890"
    },

    // Shipping information
    "shippingOption": {
        "shippingMethodName": "2nd day delivery",
        "shippingRate": 10,
        "estimatedTransitTime": "5"
    },
    "handlingFee": {
        "name": "Wrapping",
        "value": 2,
        "description": "Silk paper wrapping"
    },

    // Other information
    "additionalInfo": {},
    "paymentParams": {
        "Company name": "Unreal Company",
        "Job position": "Manager",
        "PO number": "123abcd",
        "Buyer's full name": "John Smith"
    }
}

A JSON object of type 'Order’ with the following fields:

Order

FieldTypeDescription
orderNumbernumber/stringUnique order number without prefixes/suffixes, e.g. 34. COMING SOON: For completed orders orderNumber will work as described earlier. For abandoned sales i.e. the paymentStatus is INCOMPLETE, orderNumber will be a unique cart ID of type string and it will look like this: "551c5edd-5fae-40c1-99a9-25095df20e4f"
vendorOrderNumberstringOrder number with prefix and suffix defined by admin, e.g. ABC34-q. COMING SOON: For completed orders, vendorOrderNumber will work as described earlier. For abandoned sales i.e. the paymentStatus is INCOMPLETE, vendorOrderNumber will be a unique cart ID and will look like this: "551c5edd-5fae-40c1-99a9-25095df20e4f"
subtotalnumberOrder subtotal
totalnumberOrder total cost
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total
customerTaxExemptboolean true if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidboolean true if customer tax ID is valid, false otherwise
reversedTaxAppliedboolean true if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringOrder comments
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
membershipBasedDiscountnumberSum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscountnumberThe sum of discount based on subtotal AND customer group. Is included into the discount field
discountnumberThe sum of all applied discounts except for the coupon discount. To get the total order discount, take the sum of couponDiscount and discount field values
usdTotalnumberOrder total in USD
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
updateDatedateThe date/time of the last order change, e.g 2014-06-06 18:57:19 +0000
createTimestampnumberThe date of order placement in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberThe date of the last order change in UNIX Timestamp format, e.g 1427268654
customerGroupIdnumberCustomer group ID
customerGroupstringThe name of group (membership) the customer belongs to
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn’t belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredboolean true/false: shows whether the item requires shipping
trackQuantityboolean true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlyboolean true/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalboolean true/false: shows whether the item has downloadable files attached
productAvailableboolean true/false: shows whether the product is available in the store
couponAppliedboolean true/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item
filesArray<OrderItemProductFile>Files attached to the order item
productDimensions<ProductDimensions>Product dimensions info

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping

OrderItemProductFile

FieldTypeDescription
productFileIdnumberInternal unique file ID
maxDownloadsnumberMax allowed number of file downloads. See E-goods article in Ecwid Help center for the details
remainingDownloadsnumberRemaining number of download attempts
expirestringDate/time of the customer download link expiration
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringLink to the file. Be careful: the link contains the API access token. Make sure you do not display the link as is in your application and not give it to a customer.
customerUrlstringFile download link that is sent to the customer when the order is paid

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered option value(s) as a string. For the CHOICES type, provides a string with all chosen values (comma-separated). You can use this to simply print out all selected values.
valuesArrayArraySelected option values as an array. For the CHOICES type, provides an array with the chosen values so you can iterate through them in your app.
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

OrderItemOptionFile

FieldTypeDescription
idnumberFile ID
namestringFile name
sizenumberFile size in bytes
urlstringFile URL

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by ’\n’
citystringCity
countryCodestringTwo-letter country code
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name, e.g. New York
phonestringPhone number

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringShipping carrier name, e.g. USPS
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Possible formats: number “5”, several days estimate “4-9”
isPickupboolean true if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
order_totalnumberMinimum order subtotal the discount applies to
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
404The order is not found
405Method not allowed. Can occur when using POST instead of PUT HTTP request method
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get order invoice

Get invoice HTML code for a specific order placed in a store.

Request example

GET /api/v3/4870020/orders/20/invoice?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}/invoice?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber

Response

Response example (HTML)

<!DOCTYPE html>
<html>
    <head>
        <title>Order - #ab645ad</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=Edge">
        <script>
        function printFrame() {
            window.document.close();
            window.focus();
            window.print();
            setTimeout(function(){window.close();}, 1);
        }
    </script>
    </head>
    <body onload="printFrame()">
        <!-- Invoice styles -->
        <style type="text/css">
html,body {
    min-height:50%;
    margin:0;
    padding:0;
}

body {
    background-color:#fff;
    width:210mm;
    -moz-box-sizing:border-box;
    box-sizing:border-box;
    padding:20mm 10mm 15mm;
}

body > div {
    height:100%;
}

body p:empty {
    display:none;
}

body a {
    text-decoration:none;
    color:#000;
}

body table {
    border-collapse:collapse;
    border-spacing:0;
}

body .body {
    height:100%;
    width:130mm;
    margin:0 auto;
}

body .body td {
    vertical-align:top;
    height:0;
    font-family:Arial, Helvetica, "Sans Serif";
    font-size:8pt;
    line-height:10pt;
    color:#000;
    padding:0;
}

body .body td.footer {
    height:100%;
    text-align:center;
    vertical-align:bottom;
}

body .body td.footer div {
    border-bottom:1px solid #000;
    padding:10mm 0 5pt;
}

body .body .invoice td td {
    vertical-align:top;
    padding:0;
}

body .body .invoice p {
    margin:2pt 0;
}

body .body .invoice .store-info {
    width:100%;
    margin-bottom:16pt;
}

body .body .invoice .store-info .invoice-logo {
    max-height:25mm;
    max-width:100%;
    width:auto;
    display:block;
    margin:0 0 5mm;
}

body .body .invoice .store-info .store-title {
    font-size:10pt;
    line-height:12pt;
    font-weight:600;
    padding:5pt 0;
}

body .body .invoice .store-info .store-main-info {
    width:89mm;
    padding-right:5mm;
}

body .body .invoice .store-info .store-main-info .title-detached {
    margin-top:5pt;
    margin-bottom:5pt;
}


body .body .invoice .store-info .store-customer-info {
    vertical-align:top;
}

body .body .invoice .store-info .store-customer-info p {
    max-width:60mm;
    word-wrap:break-word;
}

body .body .invoice td.invoice-row,body .body .invoice .invoice-row > tr:first-child > td {
    border-top:1px solid #000;
}

body .body .invoice .order-comment {
    padding-bottom: 12pt;
}

body .body .invoice .order-info {
    margin-bottom:11pt;
    padding:0;
}

body .body .invoice .order-items {
    margin-bottom:16pt;
    padding:0;
}

body .body .invoice .order-info td,body .body .invoice .order-items td {
    width:42mm;
    padding-right:5mm;
}

body .body .invoice .order-info td:last-child,body .body .invoice .order-items td:last-child {
    width:auto;
}

body .body .invoice .order-info .title,body .body .invoice .order-items .title {
    font-weight:600;
    padding-top:5pt;
    padding-bottom:12pt;
    margin:0;
}

body .body .invoice .order-info td:last-child {
    padding-right:0;
}

body .body .invoice .order-info p {
    max-width:42mm;
    word-wrap:break-word;
}

body .body .invoice .order-info .order-comment p {
    max-width: 100%;
    word-break: break-all;
    white-space: pre-wrap;
}

body .body .invoice .order-comment-title {
    margin-bottom: 4pt; 
}

body .body .invoice .order-items table tbody tr:last-child td {
    padding-bottom:3pt;
}

body .body .invoice .order-items .title {
    padding-bottom:5pt;
}

body .body .invoice .order-items .order-item-desc {
    width:87mm;
}

body .body .invoice .order-items .order-item-count {
    width:11mm;
}

body .body .invoice .order-items .order-item-count,body .body .invoice .order-items .order-item-total {
    text-align:right;
    padding-right:1mm;
}

body .body .invoice .order-items .order-item-total {
    padding-right:2mm;
    white-space: nowrap;
}

body .body .invoice .order-items .order-total td {
    padding-top:1pt;
    padding-bottom:1pt;
}

body .body .invoice,body .body .invoice .order-items table {
    width:100%;
}

body .body .invoice td,body .body .invoice .order-items table td {
    padding:0 1mm;
}

body .body .invoice .text-uppercase,body .body .invoice .order-info .title::first-letter,body .body .invoice .order-items .title::first-letter {
    text-transform:uppercase;
}

body .body .invoice .text-bold,body .body .invoice .order-items .order-item-title {
    font-weight:600;
}

body .body .invoice .store-info .store-main-info .url,body .body .invoice .order-info .title-detached,body .body .invoice .order-items .title-detached {
    margin-bottom:5pt;
}

body .body .invoice .store-info .store-main-info p,body .body .invoice .order-items .order-item-desc p {
    max-width:87mm;
    word-wrap:break-word;
}

body .body .invoice .order-items .order-item-desc .order-discount-coupon {
    max-width: 64mm;
}

body .body .invoice .order-items table tbody tr td,body .body .invoice .order-items .order-total tr:first-child td {
    padding-top:7pt;
}

@media print{
    * {
        -webkit-print-color-adjust:exact;
    }

    html,body {
        height:100%;
    }

    body {
        padding:0;
    }

    @page {
        margin:20mm 0 15mm;
    }
}
</style>
        <!-- Invoice body markup -->
        <table class="body">
            <tbody>
                <tr>
                    <td>
                        <table class="invoice">
                            <tbody>
                                <!-- Your company information -->
                                <tr>
                                    <td>
                                        <table class="store-info">
                                            <thead>
                                                <!-- Invoice logo -->
                                                <tr>
                                                    <td colspan="2" class="store-title">
                                                        <!-- Store name -->
                                                        <span>Awesome store</span>
                                                    </td>
                                                </tr>
                                            </thead>
                                            <tbody>
                                                <tr>
                                                    <!-- Company information: store URL, tax ID, company name, address and contact information -->
                                                    <td class="store-main-info">
                                                        <p class="url">    superstore.com
</p>
                                                        <p class="title-detached">Tax registration ID: 1234567</p>
                                                        <p>Cool slippers for dogs</p>
                                                        <p>5th Avenue</p>
                                                        <p>New York, NY 10002</p>
                                                        <p>United States</p>
                                                    </td>
                                                    <td class="store-customer-info">
                                                        <p>
                                                            <b>Customer service</b>
                                                        </p>
                                                        <p></p>
                                                        <p>info@superstore.com</p>
                                                    </td>
                                                </tr>
                                            </tbody>
                                        </table>
                                    </td>
                                </tr>
                                <!-- Shipping and billing information -->
                                <tr>
                                    <td class="invoice-row">
                                        <table class="order-info">
                                            <thead>
                                                <tr>
                                                    <!-- Order date -->
                                                    <td colspan="2" class="title">
                                                        <span>Fri, Jun 3, '16</span>
                                                    </td>
                                                </tr>
                                            </thead>
                                            <tbody>
                                                <tr>
                                                    <!-- Customer shipping address -->
                                                    <!-- Customer billing address -->
                                                    <td>
                                                        <p class="text-uppercase">s</p>
                                                        <p></p>
                                                        <p>Mark Cool</p>
                                                        <p>New York, New York, NY</p>
                                                        <p>United States</p>
                                                        <p></p>
                                                        <p>customer@gmail.com</p>
                                                    </td>
                                                    <td>
                                                        <!-- Shipping option chosen to deliver the order -->
                                                        <p>Shipped via Ground Delivery</p>
                                                        <!-- Payment option that customer used to pay for the order -->
                                                        <p>Payment method PayPal</p>
                                                    </td>
                                                </tr>
                                            </tbody>
                                        </table>
                                    </td>
                                </tr>
                                <!-- Order comments -->
                                <!-- Order information -->
                                <tr>
                                    <td class="order-items">
                                        <table>
                                            <tbody class="invoice-row">
                                                <tr>
                                                    <td colspan="3" class="title">
                                                        <!-- Order number -->
                                                        <span>Order #ab645ad</span>
                                                    </td>
                                                </tr>
                                                <!-- Ordered items list -->
                                                <tr>
                                                    <td class="order-item-desc">
                                                        <p class="order-item-title">Galaxy SII</p>
                                                        <p>SKU : 000026</p>
                                                    </td>
                                                    <td class="order-item-count">
                                                        <p>1</p>
                                                    </td>
                                                    <td class="order-item-total text-bold">
                                                        <p>$100</p>
                                                    </td>
                                                </tr>
                                            </tbody>
                                            <!-- Order totals -->
                                            <tbody class="invoice-row order-total">
                                                <!-- Order subtotal -->
                                                <tr>
                                                    <td colspan="2" class="order-item-count">
                                                        <p>Items</p>
                                                    </td>
                                                    <td class="order-item-total">
                                                        <p>$100</p>
                                                    </td>
                                                </tr>
                                                <!-- Order shipping cost -->
                                                <tr>
                                                    <td colspan="2" class="order-item-count">
                                                        <p>Shipping</p>
                                                    </td>
                                                    <td class="order-item-total">
                                                        <p>$10</p>
                                                    </td>
                                                </tr>
                                                <!-- Order handling fee cost -->
                                                <!-- Order tax -->
                                                <!-- Order discounts total -->
                                                <tr>
                                                    <td colspan="2" class="order-item-count">
                                                        <p>Discount</p>
                                                    </td>
                                                    <td class="order-item-total">
                                                        <p>-$14</p>
                                                    </td>
                                                </tr>
                                                <!-- Order total cost -->
                                                <tr>
                                                    <td class="order-item-desc"></td>
                                                    <td class="order-item-count text-bold">
                                                        <p>Total</p>
                                                    </td>
                                                    <td class="order-item-total text-bold">
                                                        <p>$96</p>
                                                    </td>
                                                </tr>
                                            </tbody>
                                        </table>
                                    </td>
                                </tr>
                            </tbody>
                        </table>
                    </td>
                </tr>
                <!-- Invoice footer -->
                <tr>
                    <td class="footer">
                        <div>Thank you for your order!</div>
                    </td>
                </tr>
            </tbody>
        </table>
    </body>
</html>

HTML code of an invoice for the requested order number.

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
404The order is not found
405Method not allowed. Can occur when using PUT/POST/DELETE HTTP request methods instead of GET
415Unsupported content-type: expected application/json or text/json
422Cannot generate an invoice for unfinished order
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update order

This request allows you to update existing orders in the store. When updating order information, you can omit unchanged fields – they will be ignored so the resulting order will keep the corresponding information unchanged. However, please mind that if you want to update the ordered items, you should submit all the items in the request. The omitted items will be removed. This is done this way to let you remove some purchased items from the order.

Request example

PUT /api/v3/4870020/orders/20?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
        "subtotal": 35,
        "total": 45,
        "email": "newemail@example.com",
        "paymentMethod": "New payment method",
        "tax": 0,
        "paymentStatus": "CANCELLED",
        "fulfillmentStatus": "PROCESSING",
        "customerTaxExempt": false,
        "customerTaxId": "",
        "customerTaxIdValid": false,
        "reversedTaxApplied": false,
        "billingPerson": {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "My Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingPerson": {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "My Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingOption": {
            "shippingMethodName": "Fast Delivery",
            "shippingRate": 10
        },
        "items": [
            {
                "id": 41056225,
                "productId": 37208346,
                "price": 7.99,
                "productPrice": 7.99,
                "weight": 0.31,
                "sku": "00001",
                "quantity": 5,
                "shortDescription": "New description",
                "tax": 1.79,
                "shipping": 10,
                "quantityInStock": 1981,
                "name": "New name",
                "isShippingRequired": true,
                "fixedShippingRateOnly": false,
                "productAvailable": true,
                "selectedOptions": [
                    {
                        "name": "Size",
                        "value": "Big",
                        "type": "CHOICE"
                    },                  
                    {
                        "name": "Any text",
                        "value": "Test text",
                        "type": "TEXT"
                    }
                ],
                "taxes": [
                    {
                        "name": "Tax Y",
                        "value": 7,
                        "total": 4.79
                    }
                ],
                "productDimensions": {
                    "length": 34,
                    "width": 3,
                    "height": 22
                }
            }
        ],
        "hidden": false,
        "privateAdminNotes": "Must be delivered till Sunday."
    }

PUT https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber

Request body

A JSON object of type 'Order’ with the following fields:

Order

FieldTypeDescription
subtotalnumberOrder subtotal
totalnumberOrder total cost
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total
customerTaxExemptboolean true if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidboolean true if customer tax ID is valid, false otherwise
reversedTaxAppliedboolean true if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringOrder comments
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
membershipBasedDiscountnumberSum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscountnumberThe sum of discount based on subtotal AND customer group. Is included into the discount field
discountnumberThe sum of all applied discounts except for the coupon discount. To get the total order discount, take the sum of couponDiscount and discount field values
globalRefererstringURL that the customer came to the store from
customerGroupstringThe name of group (membership) the customer belongs to
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner

OrderItem

FieldTypeDescription
idnumberOrder item ID.
quantitynumberAmount purchased
namestringProduct name
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn’t belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct/Combination SKU
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
isShippingRequiredboolean true/false: shows whether the item requires shipping
trackQuantityboolean true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlyboolean true/false: shows whether the fixed shipping rate is set for the product
fixedShippingRatenumberFixed shipping rate for the product
digitalboolean true/false: shows whether the item has downloadable files attached
productAvailableboolean true/false: shows whether the product is available in the store
couponAppliedboolean true/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered value by customer. Multiple values separated by comma in a single string
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by ’\n’
citystringCity
countryCodestringTwo-letter country code
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
phonestringPhone number

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringShipping carrier name, e.g. USPS
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Formats accepted: number “5”, several days estimate “4-9”
isPickupboolean true if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP
order_totalnumberMinimum order subtotal the discount applies to

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

Response

Response example (JSON)

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated orders (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 400 Status QUEUED is deprecated, use AWAITING_PAYMENT instead
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are invalid
404The order is not found
415Unsupported content-type: expected application/json or text/json
500Cannot update the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete order

Request example

DELETE /api/v3/4870020/orders/20?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted orders (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description.

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
404The order with given number is not found
500The delete request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Create order

Request example

POST /api/v3/4870020/orders?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
        "subtotal": 30,
        "total": 40,
        "email": "example@example.com",
        "paymentMethod": "Phone order",
        "tax": 0,
        "paymentStatus": "PAID",
        "customerTaxExempt": false,
        "customerTaxId": "",
        "customerTaxIdValid": false,
        "reversedTaxApplied": false,
        "fulfillmentStatus": "AWAITING_PROCESSING",
        "createDate": "2015-09-20 19:59:43 +0000",
        "items": [
            {
                "price": 15,
                "weight": 0.32,
                "sku": "00004",
                "quantity": 2,
                "name": "Cherry"
            }
        ],
        "billingPerson": {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "My Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingPerson": {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "My Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingOption": {
            "shippingMethodName": "Fast Delivery",
            "shippingRate": 10
        },
        "hidden": false,
        "privateAdminNotes": "Must be delivered till Sunday."
    }

POST https://app.ecwid.com/api/v3/{storeId}/orders?token={token}

FieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'Order’ with the following fields:

Order

FieldTypeDescription
subtotalnumberOrder subtotal
totalnumberOrder total cost
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total
customerTaxExemptboolean true if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidboolean true if customer tax ID is valid, false otherwise
reversedTaxAppliedboolean true if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
. Ignored when creating orders with public token
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP
. Ignored when creating orders with public token
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringOrder comments
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
membershipBasedDiscountnumberSum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscountnumberThe sum of discount based on subtotal AND customer group. Is included into the discount field
discountnumberThe sum of applied discounts without coupon discount.
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
customerGroupstringThe name of group (membership) the customer belongs to
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner. Ignored when creating orders with public token

OrderItem

FieldTypeDescription
namestringProduct name
quantitynumberAmount purchased
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn’t belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
isShippingRequiredboolean true/false: shows whether the item requires shipping
trackQuantityboolean true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlyboolean true/false: shows whether the fixed shipping rate is set for the product
fixedShippingRatenumberFixed shipping rate for the product
digitalboolean true/false: shows whether the item has downloadable files attached
productAvailableboolean true/false: shows whether the product is available in the store
couponAppliedboolean true/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item
productDimensions<ProductDimensions>Product dimensions info

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered value by customer. Multiple values separated by comma in a single string
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by ’\n’
citystringCity
countryCodestringTwo-letter country code
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
phonestringPhone number

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringShipping carrier name, e.g. USPS
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Formats accepted: number “5”, several days estimate “4-9”
isPickupboolean true if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP
order_totalnumberMinimum order subtotal the discount applies to

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

Response

Response example (JSON)

{
    "id": 20
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberThe number of created order in the store

Errors

Error response example

HTTP/1.1 400 Field OrderItem.quantity is absent
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are invalid
404The customer or any other linked object is not found in the store
500Cannot create an order because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload item option file

Using this method, you can attach a file to an order item (implying that the order item has a 'file upload’ option). Request parameters specify which order, item and option should be updated. Request body is the file itself (binary data). Maximum allowed file size is 100Mb.

Request example

POST /api/v3/4870020/orders/20/items/987653/options/Attach+your+image?fileName=my_photo.jpg&token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/4870020/orders/20/items/987653/options/Attach+your+image?fileName=my_photo.jpg&token=123456789abcd';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/4870020/orders/20/items/987653/options/Attach+your+image?fileName=my_photo.jpg&token=123456789abcd"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}/items/{itemId}/options/{optionName}?fileName={fileName}token={token}

NameTypeDescription
storeIdnumberEcwid store ID
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber
itemIdnumberOrder item ID
optionNamestringItem product option name, e.g. Upload your photo
fileNamestringUploaded file name
tokenstringoAuth token

When uploading an item option file, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
    "id": 6005003
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal file ID

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescriptionCode (optional)
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Order, order item or item option is not found
409Product option type is not FILESOPTIONS_IS_NOT_FILES_TYPE
413The file is too large. Maximum allowed file size is 100Mb.
415Unsupported content-type: expected application/octet-stream
500Uploading of the file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete item option file

Using this method, you can remove a file attached to an order item option by customer.

Request example

DELETE /api/v3/4870020/orders/20/items/987653/options/Attach+your+image/files/1838839292388?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json

DELETE https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}/items/{itemId}/options/{optionName}/files/{fileId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber
itemIdnumberOrder item ID
optionNamestringItem product option name, e.g. Upload your photo
fileIdnumberOption file’s internal ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted files (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Order, order item or item option is not found
409Product option type is not FILES
500Request failed – there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
errorCodestringError code

Delete all item option’s files

Using this method, you can remove all files attached to an order item option by customer.

Request example

DELETE /api/v3/4870020/orders/20/items/987653/options/Attach+your+image/files?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}/items/{itemId}/options/{optionName}/files?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber
itemIdnumberOrder item ID
optionNamestringItem product option name, e.g. Upload your photo
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 2
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted files

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Order, order item or item option is not found
500Request failed – there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
errorCodestringError code

Cart

Calculate order details

This method will calculate and return shipping rates and taxes for the order sent in a request. You can use it for your custom checkout process prior to creating an actual order in the store. Requests to this endpoint don’t create any new orders in the actual store. See Shipping and Taxes help articles to find out more information.

Request example

POST /api/v3/4870020/order/calculate?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
        "items": [
            {
                "price": 15,
                "weight": 0.32,
                "sku": "00004",
                "quantity": 2,
                "isShippingRequired": false,
                "name": "Cherry"
            },
            {
                "price": 4.22,
                "weight": 0.12,
                "sku": "00014",
                "quantity": 2,
                "isShippingRequired": true,
                "name": "Apple"
            }
        ],
        "billingPerson": {
            "name": "Peter Doe",
            "companyName": "Awesome store inc.",
            "street": "My Personal Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingPerson": {
            "name": "Mary Watson",
            "companyName": "Best Brownies Inc.",
            "street": "The other street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90001",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        }
}

POST https://app.ecwid.com/api/v3/{storeId}/order/calculate?token={token}

FieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type ‘Order’ with the following fields:

Order

FieldTypeDescription
emailstringCustomer email address
ipAddressstringCustomer IP
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information. If no shippingPerson provided, the values are taken from billingPerson

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn’t belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredboolean true/false: shows whether the item requires shipping. If not specified, the value is considered true
trackQuantityboolean true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlyboolean true/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalboolean true/false: shows whether the item has downloadable files attached
productAvailableboolean true/false: shows whether the product is available in the store
couponAppliedboolean true/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered option value(s) as a string. For the CHOICES type, provides a string with all chosen values (comma-separated). You can use this to simply print out all selected values.
valuesArrayArraySelected option values as an array. For the CHOICES type, provides an array with the chosen values so you can iterate through them in your app.
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

OrderItemOptionFile

FieldTypeDescription
idnumberFile ID
namestringFile name
sizenumberFile size in bytes
urlstringFile URL

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress
citystringCity
countryCodestringTwo-letter country code
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name, e.g. New York
phonestringPhone number

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Response

Response example

{
  "subtotal": 38.44,
  "total": 3093.93,
  "tax": 3.87,
  "couponDiscount": 0,
  "paymentStatus": "INCOMPLETE",
  "fulfillmentStatus": "AWAITING_PROCESSING",
  "volumeDiscount": 15,
  "membershipBasedDiscount": 0.77,
  "totalAndMembershipBasedDiscount": 0,
  "discount": 20,
  "usdTotal": 0,
  "createDate": "2016-02-25 15:12:14 +0000",
  "createTimestamp": 1456413134,
  "items": [
    {
      "id": 938012012,
      "productId": 123456789,
      "price": 15,
      "productPrice": 0,
      "sku": "00004",
      "quantity": 2,
      "tax": 0,
      "shipping": 0,
      "quantityInStock": 0,
      "name": "Cherry",
      "isShippingRequired": true,
      "weight": 0.32,
      "trackQuantity": false,
      "fixedShippingRateOnly": false,
      "fixedShippingRate": 0,
      "digital": false,
      "productAvailable": true,
      "couponApplied": false
    },
    {
      "id": 1023921938,
      "productId": 123456788,
      "price": 4.22,
      "productPrice": 0,
      "sku": "00014",
      "quantity": 2,
      "tax": 0,
      "shipping": 0,
      "quantityInStock": 0,
      "name": "Apple",
      "isShippingRequired": true,
      "weight": 0.12,
      "trackQuantity": false,
      "fixedShippingRateOnly": false,
      "fixedShippingRate": 0,
      "digital": false,
      "productAvailable": true,
      "couponApplied": false
    }
  ],
  "billingPerson": {
    "name": "Peter Doe",
    "companyName": "Awesome store inc.",
    "street": "My Personal Street",
    "city": "San Diego",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "90002",
    "stateOrProvinceCode": "CA",
    "stateOrProvinceName": "California",
    "phone": "123141321"
  },
  "shippingPerson": {
    "name": "Mary Watson",
    "companyName": "Best Brownies Inc.",
    "street": "The other street",
    "city": "San Diego",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "90001",
    "stateOrProvinceCode": "CA",
    "stateOrProvinceName": "California",
    "phone": "123141321"
  },
  "shippingOption": {
    "shippingCarrierName": "U.S.P.S.",
    "shippingMethodName": "U.S.P.S. Priority Mail Express 2-Day™",
    "shippingRate": 3071.62,
    "estimatedTransitTime": "1"
  },
  "availableShippingOptions": [
    {
      "shippingCarrierName": "U.S.P.S.",
      "shippingMethodName": "U.S.P.S. Priority Mail Express 2-Day™",
      "shippingRate": 3071.62,
      "estimatedTransitTime": "1"
    },
    {
      "shippingCarrierName": "U.S.P.S.",
      "shippingMethodName": "U.S.P.S. Priority Mail Express 2-Day™ Hold For Pickup",
      "shippingRate": 3071.62,
      "estimatedTransitTime": "1"
    },
    {
      "shippingCarrierName": "U.S.P.S.",
      "shippingMethodName": "U.S.P.S. Library Mail Parcel",
      "shippingRate": 234.87,
      "estimatedTransitTime": "2-9"
    },
    {
      "shippingCarrierName": "U.S.P.S.",
      "shippingMethodName": "U.S.P.S. Media Mail Parcel",
      "shippingRate": 246.34,
      "estimatedTransitTime": "2-9"
    },
    {
      "shippingMethodName": "Fixed rate",
      "shippingRate": 10
    },
    {
      "shippingMethodName": "Local store pickup",
      "isPickup": true,
      "pickupInstruction": "Bring your receipt and order number."
    }
  ],
  "availableTaxes": [
    {
      "id": 1939536453,
      "name": "VAT",
      "enabled": true,
      "includeInPrice": true,
      "useShippingAddress": true,
      "taxShipping": false,
      "appliedByDefault": true,
      "defaultTax": 21,
      "rules": [
        {
          "zoneId": "3772-1438789680791",
          "tax": 21
        }
      ]
    },
    {
      "id": 1117939047,
      "name": "World tax",
      "enabled": false,
      "includeInPrice": false,
      "useShippingAddress": true,
      "taxShipping": false,
      "appliedByDefault": true,
      "defaultTax": 5,
      "rules": [
        {
          "zoneId": "7715-1423477610739",
          "tax": 5
        }
      ]
    }
  ],
  "handlingFee": {
    "name": "Handling Fee",
    "value": 0,
    "description": ""
  },
  "additionalInfo": {},
  "paymentParams": {},
  "discountInfo": [
    {
      "value": 15,
      "type": "ABS",
      "base": "ON_TOTAL",
      "orderTotal": 1
    },
    {
      "value": 2,
      "type": "PERCENT",
      "base": "ON_MEMBERSHIP"
    },
    {
      "value": 10,
      "type": "ABSOLUTE",
      "base": "CUSTOM",
      "description": "Buy one get one free for T-shirts"
    }
  ],
  "hidden": false
}

A JSON object of type 'Order’ with the following fields:

Order

FieldTypeDescription
subtotalnumberOrder subtotal
totalnumberOrder total cost
emailstringCustomer email address
taxnumberTax total
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status, will always be returned as INCOMPLETE
fulfillmentStatusstringFulfilment status, will always be returned as AWAITING_PROCESSING
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
membershipBasedDiscountnumberSum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscountnumberThe sum of discount based on subtotal AND customer group. Is included into the discount field
discountnumberThe sum of all applied discounts except for the coupon discount. To get the total order discount, take the sum of couponDiscount and discount field values
usdTotalnumberOrder total in USD
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
createTimestampnumberThe date of order placement in UNIX Timestamp format, e.g 1427268654
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
availableShippingOptionsArray<ShippingOptionInfo>All calculated shipping methods for this order
availableTaxesArray<TaxInfo>All calculated taxes for this order
handlingFee<HandlingFeeInfo>Handling fee details
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn’t belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredboolean true/false: shows whether the item requires shipping
trackQuantityboolean true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlyboolean true/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalboolean true/false: shows whether the item has downloadable files attached
productAvailableboolean true/false: shows whether the product is available in the store
couponAppliedboolean true/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered option value(s) as a string. For the CHOICES type, provides a string with all chosen values (comma-separated). You can use this to simply print out all selected values.
valuesArrayArraySelected option values as an array. For the CHOICES type, provides an array with the chosen values so you can iterate through them in your app.
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

OrderItemOptionFile

FieldTypeDescription
idnumberFile ID
namestringFile name
sizenumberFile size in bytes
urlstringFile URL

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress
citystringCity
countryCodestringTwo-letter country code
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name, e.g. New York
phonestringPhone number

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringShipping carrier name, e.g. USPS
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Possible formats: number “5”, several days estimate “4-9”
isPickupboolean true if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

TaxInfo

FieldTypeDescription
idnumberUnique internal ID of the tax
namestringDisplayed tax name
enabledbooleanWhether tax is enabled true / false
includeInPriceboolean true if the tax rate is included in product prices. More details: Taxes in Ecwid
useShippingAddressboolean true if the tax is calculated based on shipping address, false if billing address is used
taxShippingboolean true is the tax applies to subtotal+shipping cost . false if the tax is applied to subtotal only
appliedByDefaultboolean true if the tax is applied to all products. false is the tax is only applied to thos product that have this tax enabled
defaultTaxnumberTax value, in %, when none of the destination zones match
rulesArray<TaxRule>Tax rates

TaxRule

FieldTypeDescription
zoneIdstringDestination zone ID
taxnumberTax rate for this zone in %

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
order_totalnumberMinimum order subtotal the discount applies to
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

Errors

Error response example

HTTP/1.1 422 Unprocessable Entity
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
422No order items or incorrect items details sent
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Customers

Search customers

Request

Request examples

GET /api/v3/4870020/customers?email=johnsmith@example.com&token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/customers?keyword={keyword}&name={name}&email={email}&customerGroup={groupId}&minOrderCount={minOrderCount}&maxOrderCount={maxOrderCount}&sortBy={sortBy}&offset={offset}&limit={limit}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
keywordstringSearch term that Ecwid looks for in all customer fields
namestringCustomer name
emailstringCustomer email
groupIdnumberCustomer group ID
minOrderCountnumberMinimum number of order a customer placed
maxOrderCountnumberMaximum number of order a customer placed
sortBystringSort order. Supported values:
  • NAME_ASC default
  • NAME_DESC
  • EMAIL_ASC
  • EMAIL_DESC
  • ORDER_COUNT_ASC
  • ORDER_COUNT_DESC
  • REGISTERED_DATE_DESC
  • REGISTERED_DATE_ASC
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10

Response

Response example (JSON)

{
    "total": 3,
    "count": 3,
    "limit": 10,
    "offset": 0,
    "items": [
        {
            "id": 14145238,
            "name": "John Darling",
            "email": "demo4@ecwid.com",
            "totalOrderCount": 1,
            "customerGroupId": 12345,
            "customerGroupName": "Extra Gold"
        },
        {
            "id": 14145239,
            "name": "Michael Darling",
            "email": "demo5@ecwid.com",
            "totalOrderCount": 1
        },
        {
            "id": 14145235,
            "name": "Wendy Darling",
            "email": "demo1@ecwid.com",
            "totalOrderCount": 0,
            "customerGroupId": 0,
            "customerGroupName": "General"
        }
    ]
}

A JSON object of type ‘CustomerSearchResult’ with the following fields:

CustomerSearchResult

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe number of returned items
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
itemsArrayThe items list

CustomerSearchEntry

FieldTypeDescription
idnumberUnique internal customer ID
emailstringCustomer email
namestringCustomer full name
totalOrderCountnumberNumber of customer’s orders
customerGroupIdnumberCustomer group ID
customerGroupNamestringCustomer group name

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the customers info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get customer

Request

Request example

GET /api/v3/4870020/customers/123123?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/customers/{customerId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
customerIdnumberCustomer ID
tokenstringoAuth token

Response

Response example (JSON)

{
    "id": 15319410,
    "email": "johnsmith@example.com",
    "registered": "2014-09-01 23:25:27 +0400",
    "customerGroupId": 12345,
    "customerGroupName": "Extra Gold",
    "billingPerson": {
        "name": "John Smith",
        "companyName": "Unreal Company",
        "street": "W 3d st",
        "city": "New York",
        "countryCode": "US",
        "countryName": "United States",
        "postalCode": "10001",
        "stateOrProvinceCode": "NY",
        "stateOrProvinceName": "New York",
        "phone": "+1234567890"
    },
    "shippingAddresses": [
        {
            "id": 8315122,
            "name": "John Smith",
            "companyName": "",
            "street": "W 3d st",
            "city": "New York",
            "countryCode": "US",
            "countryName": "United States",
            "postalCode": "10001",
            "stateOrProvinceCode": "NY",
            "phone": "123567890"
        },
        {
            "id": 8315123,
            "name": "Jane Smith",
            "companyName": "",
            "street": "1733 W Madison St",
            "city": "Chicago",
            "countryCode": "US",
            "countryName": "United States",
            "postalCode": "60612",
            "stateOrProvinceCode": "IL",
            "stateOrProvinceName": "Illinois",
            "phone": ""
        }
    ],
    "taxId": "GB999 9999 73",
    "taxExempt": true,
    "taxIdValid": true
}

A JSON object of type 'Customer’ with the following fields:

Customer

FieldTypeDescription
idnumberUnique internal customer ID
emailstringCustomer email
registeredstringRegistration date, e.g 2014-06-06 18:57:19 +0400
billingPersonPersonCustomer’s billing name/address
shippingAddressesArray<ShippingAddress>Customer address book items
customerGroupIdnumberCustomer group ID
customerGroupNamestringCustomer group name
taxIdstringCustomer tax ID
taxIdValidboolean true if customer tax ID is valid, false otherwise
taxExemptboolean true if customer is tax exempt, false otherwise. Learn more

Person

FieldTypeDescription
namestringCustomer full name
companyNamestringCustomer company name
streetstringStreet
citystringCity
countryCodestringCountry code (2-letter code)
countryNamestringCountry name
postalCodestringPostal code (zip code)
stateOrProvinceCodestringState/province code
stateOrProvinceNamestringState/province name
phonestringPhone number

ShippingAddress

FieldTypeDescription
idnumberInternal address ID
namestringCustomer full name
companyNamestringCustomer company name
streetstringStreet
citystringCity
countryCodestringCountry (2-digits code)
countryNamestringCountry name
postalCodestringPostal code (zip code)
stateOrProvinceCodestringState/province code
stateOrProvinceNamestringState/province name
phonestringPhone number

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
404Customer is not found
500Cannot retrieve the customer info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Create customer

Request

Request body

POST /api/v3/4870020/customers?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "email": "example@example.com",
    "password": "ecwidiscool",
    "customerGroupId": 12345,
    "billingPerson": {
        "name": "John Smith",
        "companyName": "Imaginary Company",
        "street": "Hedgehog Street, 1",
        "city": "Bucket",
        "countryCode": "US",
        "postalCode": "90002",
        "stateOrProvinceCode": "CA",
        "phone": "11111111111"
    },
    "shippingAddresses": [
        {
            "name": "John Smith",
            "companyName": "Imaginary Company",
            "street": "W 3d st",
            "city": "New York",
            "countryCode": "US",
            "postalCode": "10001",
            "stateOrProvinceCode": "NY",
            "phone": "11111111111"
        }
      ],
    "taxId": "GB999 9999 73",
    "taxExempt": true,
    "taxIdValid": true
}

POST https://app.ecwid.com/api/v3/{storeId}/customers?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'Customer’ with the following fields:

Customer

FieldTypeDescription
emailstringCustomer email
passwordstringCustomer password
customerGroupIdnumberCustomer group ID
billingPersonCustomer’s billing name/address
shippingAddressesArray<ShippingAddress>Customer address book items
taxIdstringCustomer tax ID
taxIdValidboolean true if customer tax ID is valid, false otherwise
taxExemptboolean true if customer is tax exempt, false otherwise. Learn more

Person

FieldTypeDescription
namestringCustomer full name
companyNamestringCustomer company name
streetstringStreet
citystringCity
countryCodestringCountry (2-digits code)
postalCodestringPostal code (zip code)
stateOrProvinceCodestringState/province code
phonestringPhone number

ShippingAddress

FieldTypeDescription
idnumberInternal address ID
namestringCustomer full name
companyNamestringCustomer company name
streetstringStreet
citystringCity
countryCodestringCountry (2-digits code)
postalCodestringPostal code (zip code)
stateOrProvinceCodestringState/province code
phonestringPhone number

Response

Response example

{
    "id": 15319442
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberID of the created customer

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
409The customer with the given email already exists
415Unsupported content-type: expected application/json or text/json
500The creation request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update customer

Request

Request body

PUT /api/v3/4870020/customers?10293737&token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "email": "new-email@example.com",
    "password":"newpassword",
    "customerGroupId": 12345,
    "billingPerson": {
        "name": "New Name",
        "companyName": "Ecwid",
        "street": "Updated street",
        "city": "Bucket",
        "countryCode": "US",
        "postalCode": "90002",
        "stateOrProvinceCode": "CA",
        "phone": "11111111111"
    },
    "shippingAddresses": [
        {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "Hedgehog Street, 3",
            "city": "Bucket",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "11111111111"
        }
      ],
    "taxId": "GB999 9999 73",
    "taxExempt": true,
    "taxIdValid": true
}

PUT https://app.ecwid.com/api/v3/{storeId}/customers/{customerId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
customerIdnumberInternal customer ID

Request body

A JSON object of type 'Customer’ with the following fields:

Customer

FieldTypeDescription
emailstringCustomer email
passwordstringCustomer password
customerGroupIdnumberCustomer group ID
billingPersonCustomer’s billing name/address
shippingAddressesArray<ShippingAddress>Customer address book items
taxIdstringCustomer tax ID
taxIdValidboolean true if customer tax ID is valid, false otherwise
taxExemptboolean true if customer is tax exempt, false otherwise. Learn more

Person

FieldTypeDescription
namestringCustomer full name
companyNamestringCustomer company name
streetstringStreet
citystringCity
countryCodestringCountry (2-digits code)
postalCodestringPostal code (zip code)
stateOrProvinceCodestringState/province code
phonestringPhone number

ShippingAddress

FieldTypeDescription
idnumberInternal address ID
namestringCustomer full name
companyNamestringCustomer company name
streetstringStreet
citystringCity
countryCodestringCountry (2-digits code)
postalCodestringPostal code (zip code)
stateOrProvinceCodestringState/province code
phonestringPhone number

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of update customers (0 or 1 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
404The customer with given ID is not found
409The customer with the given email already exists
415Unsupported content-type: expected application/json or text/json
500The update request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete customer

Request example

DELETE /api/v3/4870020/customers/39847403?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/customers/{customerId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
customerIdnumberCustomer ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted customers (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
404The customer with given ID is not found
500The update request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Customer groups

In Ecwid stores merchants assign customers to specific groups in order to treat them differently. For example, for some group of people, that purchased a membership in their store, they would like to provide a discount based on subtotal at all times. Another way of using customer groups is to to show them a hidden content of a store, in case if these customers are wholesalers.

To manage customer groups in Ecwid stores, use this endpoint described below and to find out more about customer groups in Ecwid stores, check out this page

Get all customer groups

Request

Request example

GET /api/v3/4870020/customer_groups?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/customer_groups?offset={offset}&limit={limit}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10

Response

Response example (JSON)

{
    "total": 2,
    "count": 2,
    "limit": 10,
    "offset": 0,
    "items": [
        {
            "id": 0,
            "name": "General"
        },
        {
            "id": 12345,
            "name": "VIP"
        }
    ]
}

A JSON object of type ‘CustomerGroupsSearchResult’ with the following fields:

CustomerGroupsSearchResult

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe number of returned items
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
offsetnumberOffset from the beginning of the returned items list (for paging)
itemsArrayThe items list

CustomerGroupsSearchEntry

FieldTypeDescription
idnumberUnique internal customer group ID
namestringCustomer group name

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402Store doesn’t have access to customer groups feature, it’s available on Business plan an higher
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the customer groups info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get customer group

Request

Request example

GET /api/v3/4870020/customer_groups/123123?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/customer_groups/{groupId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
groupIdnumberCustomer group ID
tokenstringoAuth token

Response

Response example (JSON)

{
    "id": 12345,
    "name": "VIP"
}

A JSON object of type 'CustomerGroup’ with the following fields:

CustomerGroup

FieldTypeDescription
idnumberUnique internal customer group ID
namestringCustomer group name

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
402Store doesn’t have access to customer groups feature, it’s available on Business plan and higher
404Customer group is not found
500Cannot retrieve the customer info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Create customer group

Request

Request body

POST /api/v3/4870020/customer_groups?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "Platinum"
}

POST https://app.ecwid.com/api/v3/{storeId}/customer_groups?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'CustomerGroup’ with the following fields:

CustomerGroup

FieldTypeDescription
namestringCustomer group name

Response

Response example

{
    "id": 123456
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberID of the created customer group

Errors

Error response example

HTTP/1.1 400 Field CustomerMembership.name is absent
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
402Store doesn’t have access to customer groups feature, it’s available on Business plan and higher
415Unsupported content-type: expected application/json or text/json
500The creation request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update customer group

Request

Request body

PUT /api/v3/4870020/customer_groups?123456&token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "VIP Plus"
}

PUT https://app.ecwid.com/api/v3/{storeId}/customer_groups/{groupId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
groupIdnumberInternal customer group ID

Request body

A JSON object of type 'CustomerGroup’ with the following fields:

CustomerGroup

FieldTypeDescription
namestringCustomer group name

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of update customers (0 or 1 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
402Store doesn’t have access to customer groups feature, it’s available on Business plan and higher
404The customer group with given ID is not found
415Unsupported content-type: expected application/json or text/json
500The update request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete customer group

Request example

DELETE /api/v3/4870020/customer_groups/39847403?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/customer_groups/{groupId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
groupIdnumberCustomer ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted customers (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
402Store doesn’t have access to customer groups feature, it’s available on Business plan and higher
404The customer group with given ID is not found
500The update request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Discount Coupons

Search coupons

Request

Request example

GET /api/v3/4870020/discount_coupons?discount_type=ABS%2CPERCENT&availability=ACTIVE%2CEXPIRED&token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/discount_coupons?code={code}&discount_type={discount_type}&availability={availability}&limit={limit}&offset={offset}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items in one batch. Maximum allowed value: 100. Default value: 10
codestringCoupon code
discount_typestringComma separated list of discount types. Supported values: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
availabilitystringComma separated list of coupon states. Supported values: ACTIVE, PAUSED, EXPIRED, USEDUP
createdFromstringCoupon creation date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
Examples:
  • 1447804800
  • 2015-04-22 18:48:38 -0500
  • 2015-04-22 (this is 2015-04-22 00:00:00 UTC)
createdTostringCoupon creation date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedFromstringCoupon last update date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedTostringCoupon last update date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd

Response

Response example (JSON)

{
    "total": 3,
    "count": 3,
    "limit": 10,
    "offset": 0,
    "items": [
        {
            "id": 1231421413,
            "name": "Coupon # 1",
            "code": "MOXQ3YCWXRXA",
            "discountType": "ABS",
            "status": "ACTIVE",
            "discount": 1,
            "launchDate": "2014-06-06 08:00:00 +0400",
            "usesLimit": "UNLIMITED",
            "repeatCustomerOnly": false,
            "creationDate": "2014-06-06 18:57:19 +0400",
            "updateDate": "2017-01-10 02:03:43 +0000",
            "orderCount": 0,
            "catalogLimit": {
                "products": [
                    37208342,
                    37208338
                ],
                "categories": []
            }
        },
        {
            "id": 12314211242,
            "name": "Coupon # 3",
            "code": "O3Q4AP5FKXJ1",
            "discountType": "PERCENT",
            "status": "PAUSED",
            "discount": 5,
            "launchDate": "2014-06-06 08:00:00 +0400",
            "usesLimit": "UNLIMITED",
            "repeatCustomerOnly": false,
            "creationDate": "2014-06-06 08:00:00 +0400",
            "updateDate": "2017-02-10 08:03:43 +0000",
            "orderCount": 0
        }
    ]
}

A JSON object of type ‘DiscountCouponSearchResults’ with the following fields:

DiscountCouponSearchResults

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe number of returned items
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
itemsArray<CouponSearchEntry>The items list

CouponSearchEntry

FieldTypeDescription
idnumberInternal unique coupon ID
namestringCoupon title
codestringUnique coupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0400
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date. Format example: 2016-06-29 11:36:55 +0000
updateDatestringCoupon update date. Format example: 2016-06-29 11:36:55 +0000
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>The products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the coupon info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get coupon

Request

Request example

GET /api/v3/4870020/discount_coupons/MOXQ3YCWXRXA?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/discount_coupons/{couponIdentifier}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
couponIdentifiernumber/stringCoupon identifier in a store. It can be either unique internal coupon id OR a discount coupon code.
tokenstringoAuth token

Response

Response example (JSON)

{
    "id": 12314211242,
    "name": "Coupon # 1",
    "code": "MOXQ3YCWXRXA",
    "discountType": "ABS",
    "status": "ACTIVE",
    "discount": 1,
    "launchDate": "2014-06-06 08:00:00 +0400",
    "usesLimit": "UNLIMITED",
    "repeatCustomerOnly": false,
    "creationDate": "2014-06-06 18:57:19 +0400",
    "updateDate": "2017-02-10 08:03:43 +0000",
    "orderCount": 0,
    "catalogLimit": {
        "products": [
            37208342,
            37208338
        ],
        "categories": []
    }
}

A JSON object of type 'Coupon’ with the following fields:

Coupon

FieldTypeDescription
idnumberInternal unique coupon ID
namestringCoupon title
codestringUnique coupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch
expirationDatestringCoupon expliration date, e.g. 2014-06-06 08:00:00 +0400
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date. Format example: 2016-06-29 11:36:55 +0000
updateDatestringCoupon update date. Format example: 2016-06-29 11:36:55 +0000
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>The products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Malformed request parameters
404Coupon is not found
415Unsupported content-type: expected application/json or text/json

Create coupon

Request

Request body

POST /api/v3/4870020/discount_coupons?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "Coupon # 1",
    "code": "MOXQ3YCWXRXA",
    "discountType": "ABS",
    "status": "ACTIVE",
    "discount": 1,
    "launchDate": "2014-06-06 08:00:00 +0400",
    "usesLimit": "UNLIMITED",
    "repeatCustomerOnly": false,
    "orderCount": 0,
    "catalogLimit": {
        "products": [
            37208342,
            37208338
        ],
        "categories": []
    }
}

POST https://app.ecwid.com/api/v3/{storeId}/discount_coupons?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'Coupon’ with the following fields:

Coupon

FieldTypeDescription
namestringCoupon title
codestringUnique coupon code, length limit is 128 characters.
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING . Default is ABS
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP . Default is ACTIVE
discountnumberDiscount amount . 0 is default
launchDatestringThe date of coupon launch
expirationDatestringCoupon expliration date, e.g. 2014-06-06 08:00:00 +0400
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE . UNLIMITED is default
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers. false is default
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>The products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Response

Response example

{
    "id": 21871001,
    "code": 9698215
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberInternal unique coupon ID
codenumberCode of the created coupon

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, a JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
409The coupon with the given code already exists
415Unsupported content-type: expected application/json or text/json
500The creation request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update coupon

Request

Request body for discount coupon code

PUT /api/v3/4870020/discount_coupons/12MOXQ3YCWXRXA?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "Coupon # 1",
    "code": "MOXQ3YCWXRXA",
    "discountType": "ABS",
    "status": "ACTIVE",
    "discount": 1,
    "launchDate": "2014-06-06 08:00:00 +0400",
    "usesLimit": "UNLIMITED",
    "repeatCustomerOnly": false,
    "orderCount": 0,
    "catalogLimit": {
        "products": [
            37208342,
            37208338
        ],
        "categories": []
    }
}

Request body for discount coupon id

PUT /api/v3/4870020/discount_coupons/123213123?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "Coupon # 1",
    "code": "MOXQ3YCWXRXA",
    "discountType": "ABS",
    "status": "ACTIVE",
    "discount": 1,
    "launchDate": "2014-06-06 08:00:00 +0400",
    "usesLimit": "UNLIMITED",
    "repeatCustomerOnly": false,
    "orderCount": 0,
    "catalogLimit": {
        "products": [
            37208342,
            37208338
        ],
        "categories": []
    }
}

PUT https://app.ecwid.com/api/v3/{storeId}/discount_coupons/{couponIdentifier}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
couponIdentifiernumber/stringCoupon identifier in a store. It can be either unique internal coupon id OR a discount coupon code.

Request body

A JSON object of type 'Coupon’ with the following fields:

Coupon

FieldTypeDescription
namestringCoupon title
codestringUnique coupon code, length limit is 128 characters.
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING .
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP .
discountnumberDiscount amount .
launchDatestringThe date of coupon launch
expirationDatestringCoupon expliration date, e.g. 2014-06-06 08:00:00 +0400
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE .
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers.
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>The products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated coupons (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, a JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
409The coupon with the given code already exists
415Unsupported content-type: expected application/json or text/json
500The request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete coupon

Request example

DELETE /api/v3/4870020/discount_coupons/MOXQ3Y222CWXRXA?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/discount_coupons/{couponIdentifier}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
couponIdentifiernumber/stringCoupon identifier in a store. It can be either unique internal coupon id OR a discount coupon code.
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted coupons (1 or 0 depending on whether the request was successful). It returns 0 when the coupon with the given code is not found

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
500The request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Application

This endpoint allows you to get the status of the app in a specific Ecwid store. It’s now only identifying the billing state (subscription status) of the application. We will be adding more information to this endpoint in the future.

Get application status

Request example

GET /api/v3/4870020/application?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/application?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Response

Response example

{
    "subscription":
    {
        "startDate":"2016-06-30 08:28:28 +0000",
        "expirationDate":"2016-07-14 09:27:56 +0000",
        "status":"TRIAL"
    },
    "subscriptionStatus":"TRIAL"
}

A JSON object of type ‘Application’ with the following fields:

Application

FieldTypeDescription
subscription<SubscriptionDetails>Subscription details for the application
subscriptionStatusstringApplication status in Ecwid store. One of ACTIVE, SUSPENDED or TRIAL

SubscriptionDetails

FieldTypeDescription
startDatestringApp subscription start timestamp
expirationDatestringApp subscription end timestamp
statusstringApplication status in Ecwid store. One of ACTIVE, SUSPENDED or TRIAL

HTTP codes

HTTP StatusMeaning
415Unsupported content-type: expected application/json or text/json

How it works

Free apps:

  • Ecwid will always return ACTIVE unless application is uninstalled.

Paid apps using external billing:

  • Ecwid will always return ACTIVE unless application is uninstalled.

Paid apps using Ecwid billing:

  • Ecwid will return ACTIVE if application is successfully installed and paid by a user.
  • Ecwid will return SUSPENDED if there was an issue with prolongating subscription of this app.

Paid apps using Ecwid billing with free trial:

  • Ecwid will return TRIAL if this Ecwid store uses free trial of your application at the moment.
  • Ecwid will return ACTIVE if application is successfully installed and paid by a user.
  • Ecwid will return SUSPENDED if there was an issue with prolongating subscription of this app.

What is Ecwid billing and how do I use it?

Ecwid billing is a feature that allows to accept payments for applications. It works out of the box, so no additional development is required to use it.

You can specify free trial period for new installs and active users pay on a monthly basis. To find out more details and how to use it, please visit: http://developers.ecwid.com/make-money

Starter Site

Ecwid API features several endpoints to control the presentation of Starter site. Learn more about Ecwid Starter site: https://support.ecwid.com/hc/en-us/articles/207100069-Starter-site

Get starter site content details

Get starter site content details of an Ecwid store.

Request

Request example

GET /api/v3/4870020/startersite?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/startersite?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Response

Response example (JSON)

{
  "coverImageUrl": "https://d1howb1wwyap5o.cloudfront.net/startersite/desktop.jpg",
  "coverImageThumbnail": "data:image/jpeg;base64,/9j/4QAyRXhpZgAASUkqAAgAAAABAJiCAgAOAAAAGgAAAAAAAABnLXN0b2Nrc3R1ZGlvAAAA/+wAEUR1Y2t5AAEABAAAAB4AAP/hBLtodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtbG5zOmRjPSJodHRwOi8vcHVybC5vcmcvZGMvZWxlbWVudHMvMS4xLyIgeG1sbnM6cGhvdG9zaG9wPSJodHRwOi8vbnMuYWRvYmUuY29tL3Bob3Rvc2hvcC8xLjAvIiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOkE0OTJFNUU4Mzk2NjExRTY5ODhCRUE4MDE2OUI1NEUzIiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOkE0OTJFNUU3Mzk2NjExRTY5ODhCRUE4MDE2OUI1NEUzIiB4bXA6Q3JlYXRvclRvb2w9IkFkb2JlIFBob3Rvc2hvcCBMaWdodHJvb20gNS4wIChXaW5kb3dzKSIgcGhvdG9zaG9wOkF1dGhvcnNQb3NpdGlvbj0iQ29udHJpYnV0b3IiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0iQUM1RjYxQTNCNDQ2MEI4NEE0RUZDNTExQzAxQUI4NUQiIHN0UmVmOmRvY3VtZW50SUQ9IkFDNUY2MUEzQjQ0NjBCODRBNEVGQzUxMUMwMUFCODVEIi8+IDxkYzpyaWdodHM+IDxyZGY6QWx0PiA8cmRmOmxpIHhtbDpsYW5nPSJ4LWRlZmF1bHQiPmctc3RvY2tzdHVkaW88L3JkZjpsaT4gPC9yZGY6QWx0PiA8L2RjOnJpZ2h0cz4gPGRjOmNyZWF0b3I+IDxyZGY6U2VxPiA8cmRmOmxpPmctc3RvY2tzdHVkaW88L3JkZjpsaT4gPC9yZGY6U2VxPiA8L2RjOmNyZWF0b3I+IDxkYzp0aXRsZT4gPHJkZjpBbHQ+IDxyZGY6bGkgeG1sOmxhbmc9IngtZGVmYXVsdCI+NDc4MjE0OTE2PC9yZGY6bGk+IDwvcmRmOkFsdD4gPC9kYzp0aXRsZT4gPC9yZGY6RGVzY3JpcHRpb24+IDwvcmRmOlJERj4gPC94OnhtcG1ldGE+IDw/eHBhY2tldCBlbmQ9InIiPz7/7QBaUGhvdG9zaG9wIDMuMAA4QklNBAQAAAAAACEcAVoAAxslRxwCAAACAAIcAnQADWctc3RvY2tzdHVkaW8AOEJJTQQlAAAAAAAQabWF9sA1wBHTSIwEgOM32f/uAA5BZG9iZQBkwAAAAAH/2wCEABALCwsMCxAMDBAXDw0PFxsUEBAUGx8XFxcXFx8eFxoaGhoXHh4jJSclIx4vLzMzLy9AQEBAQEBAQEBAQEBAQEABEQ8PERMRFRISFRQRFBEUGhQWFhQaJhoaHBoaJjAjHh4eHiMwKy4nJycuKzU1MDA1NUBAP0BAQEBAQEBAQEBAQP/AABEIAHgAoAMBIgACEQEDEQH/xACbAAACAwEBAAAAAAAAAAAAAAAAAQIDBQQGAQACAwEBAAAAAAAAAAAAAAAAAwECBAUGEAACAQMDAgMFBgQDCQAAAAABAgMAEQQhEgUxQVFhE3GBkSIGobHBMkJS0WIjFHKCFfDxkqLCM0MkFhEAAgIABAMGBQMFAAAAAAAAAAERAiExEgNBUWFxkaGxIjKB0RMEFMFiI0JScjMk/9oADAMBAAIRAxEAPwDWAqVqYFO1OkTArUWqVqLUSEEbUWqVqLUSEEbU7U7UWokIFai1StRaiQgjai1StRaiQgjakakQdLG2oufLvXLnc9wPHyvDKmRkTJ1AXYuvTVtt6pa+nCG/ItWmriXFgOpppFLKbRxs3sBt8azD9aQIpOJx0cZ/T6rgsT7APxqEv1Xy2ap/tZ1xV/KR6Wu7+Vvmpdt6y4JeIxbKfGfA2pcLLhx3yHjssalipuTYeS3NVY8WCMZJc/OWJpCWEbbVexOgC9fZpevLTT8llEjJ5F3INtrSkWPgFTaK5041t4WKOaWUm++Net/5rfbVHutvG78vKC62kl7V5+Z6+fk/pnEJAEuU9rhVBsfjtFZ8n1qsWmBxiRW7yMC9vYg/GuHD4PkRqmCVub3mlC++3U1eeCy5NJ5IY7HooLmw7dhULU3gp6lnoSxcdDeAp2p2otWmTKK1FqdqdqJAjai1StRaiQI2otUrUWokCNFStVU08MC7pnCL2v3t4USTBZRWSPqXi/W9N2ZEJsJ2HyX+8VqqQwBBBB1BGoIoTTyBprNDtVU0EU6GOZFkQ/pYX+FXWotQQYc/0viSMWjkdFPVCA9v8N7VTBiYGC5x+SWaJCbQzO98dgenzKBsbyNehtQyq6lHUMjCzKwuCPMGl2203K7nkMW48n3rMqweN4vGe8eLEqFbqQoe5PgTeuhVaJSOjA2t06eys7/Tp8P5+Jn/ALdTfdjSgyQA/wAmu5NPA1Lbzkm1RkY0O7p6cbP185TSrbtKP1ehvpnHIvWlrZeo1vlUWJtauVxCJC8pKxk3O4hR8TXC/D8tJczZcsvW+2URLb/IoP21xpj8Zps42XNm/U8rMyk+/dpVtvcradLntwIvRqJ8MTctRanaimyLgVqLU6KJAVqdqdFEgK1K1SpUSAjWbyGHxrzrk8jIExlRhKpbaGItsvbX3V0cnky4uDNkQgGWMAqD5nU271lYvHJzETych/UNlRSjHb6ltzsG79Qppd3qbp4/IbSumv1G+kHHl5mPyGd/p+JABEQQrOu1dBcFVWxA8zWzwBA42OIEsIP6Ya1gR10v1te16ycqRseD+5ErRTJeJowQABF8qqwYXuRVn07y0UUa4U5bdISyHaSFJ126dqpszOCaWUdeo3fSdcWrP3J5YHpKdqUbpIu+Ng6+Km9Sp8mUjainSNEkQTjRCkju21UsbsQq3PRbnuahEv8AVgPULIiL26B65+cYQ4EMLdCsmTKD3KjbHf3t9lXYm4RYIY3YOm4+2IGuf9253K/taXebNhRR9U/AXN8iuBigBd8kx2Ktyvyj8zXF687H9QZ2PI7QQRfOLEFmYeRs5t9lX87/AO3y8kZcgQKiIB2JG5/tNRh+m3ljV1yrE9Q0dx8QQattVq3ztpnHkFnFccmz0VFOitkmUVFOiiQFRTookBUU6Apb8oJ9lEhBj/UcaPgguSNrgIymxDN4+IIFq78HHONhwwHX01AudTc6nXTxqvl+Ny83FWGDarCQOS7WAA+NXvByjaJJBCNNSryP/wBK0pbi9TfPBDnSVRLlLOHkcfi58mKPIhEuXKVVSAS6p+5vADxNW8dwmFjSTTRKWvorMbkeQq/E41sebIyJJjLNk7d522AC9FXXpXTHA6yIfVOwAqyWHzX7+2qbl01Kc2aVcO9/ItRNPTlVTaXz4fMxtrYnIGWO/wA//cXsw8611ZXUOhurC4Pka4eVjCSK63uWAqzGnaKFInj3bb/MpFrXJGho2bxKbw4SW+4pKrZLF5nVSCl2VP3ED4mopkROQo3Bj0BBq/EG/KiA1sb/AAFaJRmgzPqhi00sY7IkQHlq5++pT5ghx5ZInDHHjSQbSCdwRYx9pqnmSHz5QT0diPcAPwrKxotvC5s4Gss0UVx+xTub7TWK+3ru23hWzt+hqrbTVdVHec8EsjTCeZy8ryXkc9WLaXr1HGMDjyA9YmIPwuK8mukZt416PhJvUGSfHY5H+Ug1auG4n0aIv7GuqNOilRWkzjopUUAFSSNn1Gijqx6URoHJv+VdW/h76uvfyA6AdBVL7mnBZlq0nHgRVEXtuPif4VO5qN6kDSG283I1JLIKRNOomoARoopjQXoJMfl5SMiNDoNwIP4VMVnZl8rlmUm6Qnp59K7waKoZue1ImGKkMpsRqD7K1gAdsgG17X3DQi4rH7VsQsGiRh3UVZ4QKRk8hw2RIWmw5rytcskuu4nrZu1eZlkzMNZMCdngRzveAhbFv3Dd+Br3xFcubg4udF6OSm9f0t+pD4qe1FbRmB4JckG6BvbpWjxnImDfsyEjEgEbl0uLDwO4WNc/IYLYGY+K4Em2xSQAaq3Q27GuZygFzADpqSoNXaT9uHVBL44nvKKyzz+MOkZI/wAQpPz0II2xhgRe+8U6HyESjVorHP1CltIl/wCMVXJ9RkaJEgJ77r2qdNuTCVzN6NwhIb8jaN5eBqw3H4EdDXlpfqLM0Eax3I1IB0NOH6lz1cB4o3hH5hqp/wAp7VS+za2KTktXcSwZ6i9MGs7D5nAzLBJPSkP/AIpflPuPQ1oa1naacWTT6jU01KcjvRSoqCQqGRMsEDSP0FOSSOFGllYJGurO2gFY3O5qS8eohb5ZWBVvFfGiJw5l6VlzwRy4ZMskuQRo7EjzJ/hXaDVEO0RIEFlCiwrsxcV5zuN1i7v4+S1dKFLK3tLHjxGeQIOg1c+ArVWyqFUWA0ApRokS7Y12qP8AbU1XNlY8H52u37V1NVtZZ5Iqk8lidA1rL5Tl0w1KQJ/cZJ/Ki9B5sewqxsl51BB2RHoq9T7TVAALPoiAG35QSdBqazW+6onCWuM+CGLafHA8pNj8hkytNMC8smrMSvw0NRbiM91NlAAFzfw9wr1hZYySZQoNttlC696jJOmxh6pckGwvb3aCj8+3Cle9/In8ef7jyBWxsfl8KCSvQH76vGNNIbtZh2XdYVNcSV1Yqqxjp1JNd45ko5XDWDKde4sakFDLdtG7ixrofCljA3Noe2tROJb9TeYIvpQEoosEsCND3qQGttp95pjHQPbeSR0DAg1a0GKGCiUA2uWsetASUgbhqpsa6sfKzMYf0JZUXwvcfBriuYiLXdIdPAWqaPAoB37ifOhqrUWSfaEtYqfgaifUefFYSNHLfTVdp/5av/8AqpFUlsYPt67CfxrE3R7jtTdID1JA0pEIQQRbTrfvSnsbT/pjsbRdbu4uPfB67JdpuPTInxUyYmCSGC53KGF7+B2157k3XKkUY0RSBI9sUUalgHOrk2vXp8Zy3H4zxPZTElmsL6C3euh7HEQxARqwuyoNuvfpWOEpzwfM1VvbvR5jDzUKqvpEiOysG0Bt7Natk+qMkraOOOO2gB6AeVEqq2XPJpYLuA8xWNBFIzhfUJLa2a3en7W1SzepTCXHmK3NyyShxLZ1zczymTdRkKv8q/L9tPj8r04nWRjLJvLbr7uw6+FUnEJ6uB3IX/dXZgce80Uy4+xTuAZ3NrErpYW1qfudnb+k1pUSnhgW+03f5lqthDzNbBk9TFje1twJt4a1bGfnkB/cPtAqvEifHgWGWxeMlWI6E+VTGjv57furzt1F7rq/M3vNwG1ZM9d4vHHFu29Nd341rDHjsCoCEjXao+83rMTars56sAvuBvVxy5rWDGw8Kfsb21RP6ldWCiEviL3K2tGlxB4w8cw1aZbebG1S2LEAPVTZ3sxJoor0a6HKc8QYwEbgxYE2F21qccMMZJLpY6D5iTeiijHoR3ikhAAdGLewnQ1RJFJ19MkHqb2NFFDJQvQxrjehXTozamrUg49wdqEW6m5P2UUVHp/aT6v3EmwrgelB6i2H5mttqK40yHWHTodpt77k0UVPEjger4nc3DQhvzR7kPfoxt99dkFzggN+ksL9NAdKKKw391/8ma6+2vYjzM7ehmyl9Ay6j26VnuEK2J2kdSpLfdRRWra49iEbnDtZUJEQ3LSEDptuPvr0XDYPNRElsd0imA3liu4bdUtrRRVfuP8AVectLnT7umnqG1GuvOeOXx6GoMDM1PpsSSSSSLkn30xx2XuJ2W3WvqO1FFcH/ll6vyJ4zpOj/Lw+n4liYOWOoI8LFaTwS4yNLK7JGOpFu/sooplfxMI+v0y/Qo/qcdB//9k=",
  "coverImageMobileUrl": "https://d1howb1wwyap5o.cloudfront.net/startersite/mobile.jpg",
  "coverImageMobileThumbnail": "data:image/jpeg;base64,/9j/4QAyRXhpZgAASUkqAAgAAAABAJiCAgAOAAAAGgAAAAAAAABnLXN0b2Nrc3R1ZGlvAAAA/+wAEUR1Y2t5AAEABAAAAB4AAP/hBLtodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtbG5zOmRjPSJodHRwOi8vcHVybC5vcmcvZGMvZWxlbWVudHMvMS4xLyIgeG1sbnM6cGhvdG9zaG9wPSJodHRwOi8vbnMuYWRvYmUuY29tL3Bob3Rvc2hvcC8xLjAvIiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOkQwQTMyQkM3Mzk2NjExRTY5ODhCRUE4MDE2OUI1NEUzIiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOkQwQTMyQkM2Mzk2NjExRTY5ODhCRUE4MDE2OUI1NEUzIiB4bXA6Q3JlYXRvclRvb2w9IkFkb2JlIFBob3Rvc2hvcCBMaWdodHJvb20gNS4wIChXaW5kb3dzKSIgcGhvdG9zaG9wOkF1dGhvcnNQb3NpdGlvbj0iQ29udHJpYnV0b3IiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0iQUM1RjYxQTNCNDQ2MEI4NEE0RUZDNTExQzAxQUI4NUQiIHN0UmVmOmRvY3VtZW50SUQ9IkFDNUY2MUEzQjQ0NjBCODRBNEVGQzUxMUMwMUFCODVEIi8+IDxkYzpyaWdodHM+IDxyZGY6QWx0PiA8cmRmOmxpIHhtbDpsYW5nPSJ4LWRlZmF1bHQiPmctc3RvY2tzdHVkaW88L3JkZjpsaT4gPC9yZGY6QWx0PiA8L2RjOnJpZ2h0cz4gPGRjOmNyZWF0b3I+IDxyZGY6U2VxPiA8cmRmOmxpPmctc3RvY2tzdHVkaW88L3JkZjpsaT4gPC9yZGY6U2VxPiA8L2RjOmNyZWF0b3I+IDxkYzp0aXRsZT4gPHJkZjpBbHQ+IDxyZGY6bGkgeG1sOmxhbmc9IngtZGVmYXVsdCI+NDc4MjE0OTE2PC9yZGY6bGk+IDwvcmRmOkFsdD4gPC9kYzp0aXRsZT4gPC9yZGY6RGVzY3JpcHRpb24+IDwvcmRmOlJERj4gPC94OnhtcG1ldGE+IDw/eHBhY2tldCBlbmQ9InIiPz7/7QBaUGhvdG9zaG9wIDMuMAA4QklNBAQAAAAAACEcAVoAAxslRxwCAAACAAIcAnQADWctc3RvY2tzdHVkaW8AOEJJTQQlAAAAAAAQabWF9sA1wBHTSIwEgOM32f/uAA5BZG9iZQBkwAAAAAH/2wCEABALCwsMCxAMDBAXDw0PFxsUEBAUGx8XFxcXFx8eFxoaGhoXHh4jJSclIx4vLzMzLy9AQEBAQEBAQEBAQEBAQEABEQ8PERMRFRISFRQRFBEUGhQWFhQaJhoaHBoaJjAjHh4eHiMwKy4nJycuKzU1MDA1NUBAP0BAQEBAQEBAQEBAQP/AABEIAEMALQMBIgACEQEDEQH/xACGAAABBQEAAAAAAAAAAAAAAAAAAgMEBQYBAQADAQEAAAAAAAAAAAAAAAACAwQAARAAAQMDAQYFAwIHAQAAAAAAARECAwAhBBIxQVEyEwVxoSJCFGGRUmIGscFykqIzUxYRAAEDAgQGAwEAAAAAAAAAAAEAEQIhAzFRYRJBgZEiMgRx0UJi/9oADAMBAAIRAxEAPwC6ShKWldSmukskJQlLShKzrMkaFaXEtY1ti97gxoX6uIpnr4GrR8/F1/j1Qn96aadnxoMmPp5EbZYz7XgOHnVZ/wCY7X1NWl/T/wCOr0+HFKEmbhjR0YEGL4srlKEpSUJe23dXHWZVXdpcdro45ppUcrfjY/NK48oc4co43qN+3XyLLGSWxuYJWY5frMPqLSFPHhUjtGGH4uVJMAflSyanNUegO+uz1XprA7PK7PPcIcxxjfqJ0s6esCwts0HzpJkQRMmjVT2iYmA4GhOaukriUxhTySh8c6daMkK0IHN4pxqSlMFwGO4GiUbchLYRV26pbWOdcWHE04IW7ySftXVroNTSuSOgThADUqI3tWCyIQ6HOiGo6HPcR6irrKNq0+yKFpYjABGgYB7QAgTwFLNcLgxrnusGgknwoCTxJRgKp1D5s74yWlpDbeF6e68qc19xQbKr8FS187irp3l5J4LapalF3DafGuhxEh0UwDcFOIUDG/c+Q1yZkQkYdjo/S9o8DY1bY/eu2Tj0zhh/GQFh86x7xCzZIt97T96GyxFqK4uP6UPnVsvXtHDtOn0o43pj+hqt42WJwVsjHDiHA/zqq75nGPDlh0OY17msbLZJPc7QhNgKz2F0hmY5IOlssZO/3DwrWZHbMHIfkSTQh0rSCQCQ2/u0jfap7lkQI7twNcE+1deu3DVRMaAPF3NhhYgLnEBBwANS/mdlT4nyIr35rqLLq41l8yINbEGH0AvF1KAFBemehGidVuny+9MHrgx3GWdGyQG80mbKvygadbkVbcq+eq1SmrovrT9aaf8AHdRRVSmTLen1Wpp5monUXaPyrau/3ZP9A/jvooqb2PzzTrP65LHz70Xmeicu3ctRLp7tv0SiinDw6oD59F//2Q==",
  "coverTitle": "Your store name here",
  "coverSubtitle": "Write a brief explanation about your store. It can be a brief description, slogan, motto, etc.<br>Example: &quot;Your one stop gift shop for any occasion&quot;.",
  "whyusTitle": "Why Choose Us?",
  "whyusContent": "<p>Use this section to provide information for your customers about why your store is the best place to purchase the type of goods you sell. Be sure to highlight the things that make your products and store services unique. For example, are your items made locally, sourced from special ingredients, unique or customized? This is the section to tell your customers how great your products and services are. Free shipping? Let them know here!</p>",
  "quoteContent": "Insert a customer testimonial or a favorite quote that describes your business motto.",
  "quotePersonName": "Mary Smith",
  "quotePersonTitle": "local celebrity",
  "quotePersonImageUrl": "https://d1howb1wwyap5o.cloudfront.net/startersite/quote-portrait.png",
  "meetownerTitle": "About",
  "meetownerContent": "<p>Here you can let your customers get to know you. Tell them a little bit about yourself and why you have chosen to create this particular business. Do you have a passion, hobby or life experience that inspired you to create your business? Help customers feel connected to your purpose and inspire trust in your brand.</p>",
  "meetownerOwnerImageUrl": "https://d1howb1wwyap5o.cloudfront.net/startersite/owner-pic.png",
  "meetownerOwnerName": "Joan Doe,",
  "meetownerOwnerTitle": "store owner",
  "locationTitle": "Location",
  "locationDescription": "<p>How customers can find your offline store? Give some more details about your location: your address, store hours, and the easiest way to get to you. Leave this section empty if you do not have offline location.</p>",
  "locationAddress": "144 West D Street, Encinitas, CA 92024 USA",
  "locationLong": "-117.2967266",
  "locationLat": "33.0460986",
  "locationHours": "{\"hours\": [{\"dayto\": \"Friday\", \"hourto\": \"9:30 PM\", \"dayfrom\": \"Monday\", \"hourfrom\": \"10:00 AM\"}, {\"hourto\": \"7:00 PM\", \"dayfrom\": \"Saturday\", \"hourfrom\": \"Noon\"}, {\"dayfrom\": \"Sunday\", \"hourfrom\": \"Closed\"}], \"title\": \"Store Hours\"}",
  "contactusFacebook": "https://www.facebook.com/ecwid",
  "contactusTwitter": "https://twitter.com/ecwid",
  "contactusInstagram": "https://www.instagram.com/ecwid_team",
  "contactUsList": "{\"title\": \"Contact us\", \"channels\": [{\"type\": \"phone\", \"title\": \"Phone\", \"value\": \"1-800-555-0123\"}, {\"type\": \"email\", \"title\": \"Email\", \"value\": \"john.doe@example.com\"}], \"channelsTitle\": \"Connect with us\"}",
  "showCoverImage": true,
  "showWhyUs": true,
  "showQuote": true,
  "showInstagram": true,
  "showMeetowner": true,
  "showLocation": true,
  "showContactus": true
}

A JSON object of type ‘StarterSiteInfo’ with the following fields:

StarterSiteInfo

FieldTypeDescription
coverImageUrlstringURL to the main image, displayed in background when starter site is opened.
coverImageThumbnailbase64Thumbnail cover image.
coverImageMobileUrlstringURL to the main image, displayed in background when starter site is opened on mobiles.
coverImageMobileThumbnailbase64Thumbnail cover image for mobile devices
coverTitlestringThe main title displayed on top of cover image
coverSubtitlestringSubtitle displayed under the coverTitle
whyusTitlestringTitle for “Why us?” section
whyusContentstringText for “Why us?” section. HTML tags allowed: p,u,b,i,sup,a
quoteContentstringCustomer testimonial about a store. HTML tags allowed: p,u,b,i,sup,a
quotePersonNamestringCustomer name, who left a testimonial
quotePersonTitlestringTitle or occupance of customer with testimonial
quotePersonImageUrlstringURL to a photo of a customer with testimonial
meetownerTitlestringStore owner “About owner” section title
meetownerContentstringText for the “About owner” section. HTML tags allowed: p,u,b,i,sup,a
meetownerOwnerImageUrlstringURL to owner photo in the “About owner” section
meetownerOwnerNamestringStore owner’s name in the “About owner” section
meetownerOwnerTitlestringStore owner’s occupation/title in the “About owner” section
locationTitlestringTitle of the “Location” block
locationDescriptionstringText for the “Location” block. HTML tags allowed: p,u,b,i,sup,a
locationAddressstringAddress line for store’s location
locationLongstringLongitude coordinate of a store
locationLatstringLattitude coordinate of a store
locationHours<LocationHoursInfo>Working hours of a store
contactusFacebookstringURL to store’s Facebook page
contactusTwitterstringURL to store’s Twitter profile
contactusPintereststringURL to store’s Twitter profile
contactusInstagramstringURL to store’s Twitter profile
contactusInstagramIdstringInstagram ID of a store
contactusFoursquarestringURL to store’s Foursquare profile
contactusYelpstringURL to store’s Yelp profile
contactusVkstringURL to store’s Vk profile
contactusTumblrstringURL to store’s Tumblr profile
contactusEtsystringURL to store’s Etsy profile
contactusGooglestringURL to store’s Google+ profile
contactusYoutubestringURL to store’s Youtube profile
contactusVimeostringURL to store’s Vimeo profile
contactusWechatstringURL to store’s Wechat profile
contactusWhatsappstringURL to store’s Whatsapp profile
contactusTelegramstringURL to store’s Telegram profile
contactusMessengerstringURL to store’s Messenger profile
contactusLinestringURL to store’s Line profile
contactusViberstringURL to store’s Viber profile
contactUsList<ContactUsListInfo>Contact a store block
showCoverImageboolean true if “Cover image” section is shown. false otherwise. Default is true
showWhyUsboolean true if “Why Us?” section is shown. false otherwise. Default is true
showQuoteboolean true if quote section is shown. false otherwise. Default is true
showInstagramboolean true if Instagram feed section is shown. false otherwise. Default is true
showMeetownerboolean true if “Meet the Owner” section is shown. false otherwise. Default is true
showLocationboolean true if store location section is shown. false otherwise. Default is true
showContactusboolean true if “Contact Us” section is shown. false otherwise. Default is true

LocationHoursInfo

FieldTypeDescription
titlestringLocation working hours title
hours<LocationHoursDetailedInfo>Detailed location working hours information

LocationHoursDetailedInfo

FieldTypeDescription
dayfromstringDay of the week at the start of period
daytostringDay of the week at the end of period
hourfromstringOpening hours of a working day
hourtostringClosing hours of a working day

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
403Access token doesn’t have update_store_profile scope
415Unsupported content-type: expected application/json or text/json
500Server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Create and update starter site content details

Update information displayed on starter site of a store

Request

Request example

PUT /api/v3/4870020/startersite?token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

PUT https://app.ecwid.com/api/v3/{storeId}/startersite?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request example (JSON)

{
  "coverTitle": "Your store name here",
  "coverSubtitle": "Write a brief explanation about your store. It can be a brief description, slogan, motto, etc.<br>Example: &quot;Your one stop gift shop for any occasion&quot;.",
  "whyusTitle": "Why Choose Us?",
  "whyusContent": "<p>Use this section to provide information for your customers about why your store is the best place to purchase the type of goods you sell. Be sure to highlight the things that make your products and store services unique. For example, are your items made locally, sourced from special ingredients, unique or customized? This is the section to tell your customers how great your products and services are. Free shipping? Let them know here!</p>",
  "quoteContent": "Insert a customer testimonial or a favorite quote that describes your business motto.",
  "quotePersonName": "Mary Smith",
  "quotePersonTitle": "local celebrity",
  "quotePersonImageUrl": "https://d1howb1wwyap5o.cloudfront.net/startersite/quote-portrait.png",
  "meetownerTitle": "About",
  "meetownerContent": "<p>Here you can let your customers get to know you. Tell them a little bit about yourself and why you have chosen to create this particular business. Do you have a passion, hobby or life experience that inspired you to create your business? Help customers feel connected to your purpose and inspire trust in your brand.</p>",
  "meetownerOwnerImageUrl": "https://d1howb1wwyap5o.cloudfront.net/startersite/owner-pic.png",
  "meetownerOwnerName": "Joan Doe,",
  "meetownerOwnerTitle": "store owner",
  "locationTitle": "Location",
  "locationDescription": "<p>How customers can find your offline store? Give some more details about your location: your address, store hours, and the easiest way to get to you. Leave this section empty if you do not have offline location.</p>",
  "locationAddress": "144 West D Street, Encinitas, CA 92024 USA",
  "locationLong": "-117.2967266",
  "locationLat": "33.0460986",
  "locationHours": "{\"hours\": [{\"dayto\": \"Friday\", \"hourto\": \"9:30 PM\", \"dayfrom\": \"Monday\", \"hourfrom\": \"10:00 AM\"}, {\"hourto\": \"7:00 PM\", \"dayfrom\": \"Saturday\", \"hourfrom\": \"Noon\"}, {\"dayfrom\": \"Sunday\", \"hourfrom\": \"Closed\"}], \"title\": \"Store Hours\"}",
  "contactusFacebook": "https://www.facebook.com/ecwid",
  "contactusTwitter": "https://twitter.com/ecwid",
  "contactusInstagram": "https://www.instagram.com/ecwid_team",
  "contactUsList": "{\"title\": \"Contact us\", \"channels\": [{\"type\": \"phone\", \"title\": \"Phone\", \"value\": \"1-800-555-0123\"}, {\"type\": \"email\", \"title\": \"Email\", \"value\": \"john.doe@example.com\"}], \"channelsTitle\": \"Connect with us\"}",
  "showCoverImage": true,
  "showWhyUs": true,
  "showQuote": false,
  "showInstagram": true,
  "showMeetowner": true,
  "showLocation": false,
  "showContactus": true
}

A JSON object of type 'StarterSiteInfo’ with the following fields:

StarterSiteInfo

FieldTypeDescription
coverTitlestringThe main title displayed on top of cover image
coverSubtitlestringSubtitle displayed under the coverTitle
whyusTitlestringTitle for “Why us?” section
whyusContentstringText for “Why us?” section. HTML tags allowed: p,u,b,i,sup,a
quoteContentstringCustomer testimonial about a store. HTML tags allowed: p,u,b,i,sup,a
quotePersonNamestringCustomer name, who left a testimonial
quotePersonTitlestringTitle or occupance of customer with testimonial
meetownerTitlestringStore owner “About owner” section title
meetownerContentstringText for the “About owner” section. HTML tags allowed: p,u,b,i,sup,a
meetownerOwnerNamestringStore owner’s name in the “About owner” section
meetownerOwnerTitlestringStore owner’s occupation/title in the “About owner” section
locationTitlestringTitle of the “Location” block
locationDescriptionstringText for the “Location” block. HTML tags allowed: p,u,b,i,sup,a
locationAddressstringAddress line for store’s location
locationLongstringLongitude coordinate of a store
locationLatstringLattitude coordinate of a store
locationHours<LocationHoursInfo>Working hours of a store
contactusFacebookstringURL to store’s Facebook page
contactusTwitterstringURL to store’s Twitter profile
contactusPintereststringURL to store’s Twitter profile
contactusInstagramstringURL to store’s Twitter profile
contactusInstagramIdstringInstagram ID of a store
contactusFoursquarestringURL to store’s Foursquare profile
contactusYelpstringURL to store’s Yelp profile
contactusVkstringURL to store’s Vk profile
contactusTumblrstringURL to store’s Tumblr profile
contactusEtsystringURL to store’s Etsy profile
contactusGooglestringURL to store’s Google+ profile
contactusYoutubestringURL to store’s Youtube profile
contactusVimeostringURL to store’s Vimeo profile
contactusWechatstringURL to store’s Wechat profile
contactusWhatsappstringURL to store’s Whatsapp profile
contactusTelegramstringURL to store’s Telegram profile
contactusMessengerstringURL to store’s Messenger profile
contactusLinestringURL to store’s Line profile
contactusViberstringURL to store’s Viber profile
contactUsList<ContactUsListInfo>Contact a store block
showCoverImagebooleanSet to false to hide the “Cover image” section. true otherwise. Default is true
showWhyUsbooleanSet to false to hide “Why Us?” section. true otherwise. Default is true
showQuotebooleanSet to false to hide quote section. true otherwise. Default is true
showInstagrambooleanSet to false to hide Instagram feed section. true otherwise. Default is true
showMeetownerbooleanSet to false to hide “Meet the Owner” section. true otherwise. Default is true
showLocationbooleanSet to false to hide store location section. true otherwise. Default is true
showContactusbooleanSet to false to hide “Contact Us” section. true otherwise. Default is true

LocationHoursInfo

FieldTypeDescription
titlestringLocation working hours title
hours<LocationHoursDetailedInfo>Detailed location working hours information

LocationHoursDetailedInfo

FieldTypeDescription
dayfromstringDay of the week at the start of period
daytostringDay of the week at the end of period
hourfromstringOpening hours of a working day
hourtostringClosing hours of a working day

Response

Response example

{
    "id": 1003
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
idnumberThe store ID of the store where the settings were changed.

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
403Access token doesn’t have update_store_profile scope
415Unsupported content-type: expected application/json or text/json
500Server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload cover image

Upload starter site cover. The image itself is to be placed in the request body.

Request example

POST /api/v3/4870020/startersite/cover?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/startersite/cover?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/startersite/cover?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/startersite/cover?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

When uploading a starter site cover, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
  "coverImageUrl": "https://s3.amazonaws.com/images.ecwid.com/startersite/images/123456/1468931238307.jpg",
  "coverImageMobileUrl": "https://s3.amazonaws.com/images.ecwid.com/startersite/images/123456/1468931236454.jpg",
  "coverImageThumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAQCAwMDAgQDAwMEBAQEBQkGBQUFBQsICAYJDQsNDQ0LDAwOEBQRDg8TDwwMEhgSExUWFxcXDhEZGxkWGhQWFxb/2wBDAQQEBAUFBQoGBgoWDwwPFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhb/wgARCABpAKgDASIAAhEBAxEB/8QAHAAAAQUBAQEAAAAAAAAAAAAABAECAwUGAAcI/8QAGAEAAwEBAAAAAAAAAAAAAAAAAAECAwT/2gAMAwEAAhADEAAAAfCV7unnenSEoqopkcxynpHTSoZB5HLonNBjmyuoWo0p7F5uPu4pjkV09UUhHcaA7Z2KWJO5KDp1RE0loQRHiDhbIlOJX8VFzuHsLDTKZ5g68YnlnpV6YOM1EWW1DaaQ6bwlR6VRMwSaajGPUa+oRRPJn0zqVMFbi5edfQDPJ5clvisegZqY3r0vbLA7d8wm4xuax39Fj8mPZss6LKwoWvBQbJR2GkWoYdVSP6t4v0qvgGzNNTVCiCGNrNjQNqL9Sw6AbOmjMYqlnglAmnPBmoXQkXmLHLHYzl5XezjS3hYkVT2i8joc6tO02WnmvSDaMkzljkRtox0YqQayyOdvhfaMpYpx3TOXirOVCL52dK9AkR0zdOecVNNJaTU85hIQMPu3OXotjnU8jGfDnsIw0QbOdzr/xAArEAABBAIBAgUEAgMAAAAAAAACAAEDBAUREhATBhQVITEgIjJBM0IWMDX/2gAIAQEAAQUCQ9GXF9D14umAlxda9kTLiiDS100tfQzJkSZMmdNJ7jIn/JvZbTu/HknPYktpk/0N0FfvfVnW1v29ltO7aRf6dKnVnsvIIC2kw7XH34JgTAu27o4CEXZOtdH6V8KBjHgQliq+G5pnfwqTB/jtiMrVeyMTx2oZq2KtTt6LbCQvDloxHAWXVnGTQicXBACsC3AmTofZF8iJEnFVAEKmSlxld7Nelj8ZUyL26vqdppTaVxw9cbB0KdeS36RjzOXHTcrGMaEIIrRyZWlkRMikcXo2zrnUtuU8MgHVrGbWKs0YxibohJnrSnLCRzr0zuXrh2GaYJTt8AjCnI1StXvT3TnGGrbxNguxksjJFO+TirxWvEU8sct+5KovPdqxec3tyRGmEmB83N2iyQk1m13FPl7syx94COzcrgoczXimryNeU9qmAQEMap4oDWSrQCR3JBiUbQqC3JWksXrdlpt6PSJQXZ4wmvWTZOo63intS4/OG9KLyw5etRcvtkRE7rGmU6AZpXqwxyC9GEmu1xhF9MwOgdmUxH2y6CH2v1r2qEjSXccxSXQ00d+4pI5oJn+YC1Jmue6w156lnscD+OSB213HYXciGXXSFSa30aGB0Nasq4RRO2gDL854JNMTKvMFqn4cbyVK7FVtl6fQXkaKKrVYWHUmWfu3PS7DDKJDJ7s8hM79GNMaaRd1XLb9v+rKL+WK0Sax7d3a7u13No322UF5K8gOoYyM/TbbDPEcR9GTLTriScCRQGvKnuvWcXjDSHS2LLn7Mac3dVzHuZA68Nh/udb6t8j8/t+jIVEnX9A+P1B+cHxa/j8Sf9ND+Vj8k6//xAAhEQACAQQCAgMAAAAAAAAAAAAAARECECExAyAEEhNBYf/aAAgBAwEBPwEbProjJBnq7ep6siBMm+tlfKlopaqSYrIrhi6MXg0fH78lcfm2cUrF0V7skKlEGB7wQJmBMryJCtIyjWTRkl2mULtN2yjfT//EAB8RAAIDAAICAwAAAAAAAAAAAAERAAIgECEDEzAxQf/aAAgBAgEBPwHBfzAjAZncr4z+y3RWKYU7nuLVQ55MU5fAqXwYanhSgUOB0Zb74QiEUSKy8qXGP//EAD4QAAEDAQQECQoFBQEAAAAAAAEAAgMRBBIhMRMiQWEFEBQgMkJRcYEjMDNScpGhsdHhU2KCksEkNUBz8PH/2gAIAQEABj8C81mt6p/g5ceB89jxbubTz5EMRfTOiF1993WoMB48/BVNOffdamBqJhmZ3lyo2eA9pD8lrW+Kg7FV88WjGNUI4IjHBnWoq/eVojE7Hq0zQMUQPtFCoiz9daTReDSqFmWdHKpG1UNQd6xKw5uqK8TWTWeN7Dma5d60ZLY5HYaja3e9cvsloawtzvOPlN1O1OkhiabnpHuFAPBFzy14rjQHFV6MZJwJGKOmlN8RNc27tH/qeX8ro15AojKBbCd2aa1lotrWbbz0X2Z1o0h6xkWhe+1SP3Uoqy2eu9rVccwCm5NfBZ3u3jJY2WQ+Co+Is70axu3K85lB3rVqsQr7LPIWnqgUV2CyRswpefcwXK7bwjE97PRNLRdZ4IxjhCC6863k2iqkiY04OyBwCuzTin5BVRWyzSttMcDu43Tm0jvUug4NiFXYurlgr1pbPeOUUeqD8USxpssY/Flqq8uhnjPVY8Ci07TWvVGCLYNJE71i6quutFe3BVsz5S0bGnBXLZpg5v4VAm3C8fmkNUXw2y85uzFXHRMd21AWNlb4YLVY1q1TIGNzDXFXSyBm+WRyBDuCqbdHAXn4qnJ7JM2myyBqfNaZ44mV9G0U+CLLNAX1FDI5aHkzaP6181CJfwfNhTK0tCLW2AX6dKS2DD4ow6OM7CVdwxVLTLJuuayPJZTd/O0ICW6RuYAvot/FcY+g7grrpMO4cfRIB7XMC8u1jhvlYFS08ms7O02uvwC0lnt9jrto51U6rqBg1WAYcQs5dR9Lkb9rT1fjh4rRG7pa0ul2s4rXtEUe4tK/ullHtBw/hVZaYZ/9dcFg6vgqVW1dixxX3V7mFo4KkfTO/bStXgSHxtDiv6eyRWf2Xk/NDAvHbhRSQzNAdmOLOlcFFwjGbrpMJbuyQZ/XxTrRLbLkgzBHSKGjldX1CPjVffi6BJ3KmjIWF7xKzB8eI50WHH0T71i13vR0Yz7QCi2OusamqFp68QFVhls4jYz6SRuHtt6J8Rh7lR8UL3Sa3lIgSPeg6WNgLfwxc+S6Lv3ldB37yqN0jU2ISvEZNTeyBRiELWluqcKYrGext77UxFl5r6eqahY/JYYczasysyi2KPp9Ikru4mnesanxVf5X3WR/cuiughPiXN1JNancVsQa2hLsquoq6JnhO36q7IKHvrzfvxZhdILpBVqCtnHgQq8Vx4qx+Dgdo/7+U+F3BsTXN2tc/wCq1WrLzg5jPaR9or9T/kv0Dnf/xAAmEAEAAgIBAwQDAQEBAAAAAAABABEhMUFRYXEQgZGhscHw0eHx/9oACAEBAAE/IX0eWAWORftNMxKSF1ZaQTU2axCzhEY1fUTDkU94d1OxnHdykQiIiJOIbl25Q1zF1ZtU96yvJ8SnMTqEbe2Kl6I3W9zhZcJi0IqZRiKjxL9CMdxpMMVsCazXHw3LLuYYvOiZOYeFNCaVxOBlxTjUItk49DcJTV1iaYmGFOxuvw/EA77Rv9UO2XokrREE7EBdYgauqXsiiGeEogjGPFmcxYBOiIgAnOENgGRMmPNKH03rnEBYsEDeT6gDFM1uUzz7hCZYThT4qBkFdlAjrdrcFktNDtHZedkFWhuCsF6zsQ5xLbEUbxpuo0aEZbQtz2QE2zXjmmv3GlcKbnf3CunSa3Y0K6LZogw0HnjxiiGbWYtBVZ8fUseoWd5WL6BIFVuaU5vJ7wcFutUYqXEwdJzG2k+YRAN6/vBHYLWO9Qr1BxYKT3uUvrF5CbNJ0HMx8K4bnwJBqWde6mZEDAgUpF8hhxc/8BlydH7fau45oRoHzR7TLXdWBvGdV3g60HOr1zgmI5Eyw1xVUfebljKziKqzpCv9mAoPIQMaWjif/vkz89Ft8ztAR/SoNaLoHP1LbsM4KZVvg+zFgmObo+JX1Fop+ZQ1gpZX1Kd8f+kfAXxbKd1UH5SUVPKg/TLjWo8v0hjKSqmC6yyv1Zip4OK8zEwSC/Zde0tCWSnlN0xZ66jNbyj/AJAgnkk/CK16rFt/c1WBXOozD0az8mMPQMp/MoZGv0BBuvwoSAF+UQOLuXdBos/USpVhP+U53N4Bh1pE7uwWX3OwGcrGxVuGr5GVsUdyTaKwzmI6sWL6Qf40aCWFTqr9E4CeJ0PZnmvsEOd23pNmXtDgtxFNesrldnvFKwkJfo7zfNxqMKE5gR+osD1/WM2l8t18mB52YaAeY6wFxprp7X8RQRXRkTjv7bjV/wC6zvvfAi/VCszLdZu+dcy9qlrl/wAaicIOuGddSVVGwA6lXM/V6lEMXItN3XzHfyNBMnhLjvcx6vpr38lKv8jOzADmDMqTwMfZT8zuPnwil1PJafurX4gESJwV1cC7Zqv5YXEN/wB3eOkq/jmU4DYDv7jWlsNqQv8A3tMUnUjd1Wo3IPS5+ZexOvxyQcFg4cJYx4RY+gV7gjhmDs7dZcfQ5bxREcXuijrO11xE5XVYs2H97ytNw9R7x3GOqsarPy4e0NZW5YT9+nuQCoe1g/cQPsstfrF+Jqw7B/Bix3LQK4/M8cPWPmdMe8Tl6O4Noy1EdalEu0ocg97lvY/MtgrzFvIam0x4JaGLS4/4NPvDs40Q9GUfS5iVwvxLd4+mnzN8I/SE4+jf1OiMfWenv4O/0Zn5/QN+n//aAAwDAQACAAMAAAAQ8d5e3VnJeA9A0oSUfcON4x+ApYqZ8KEmwRoHc+6WjAR8lJMNVxEQad8CCX33cF/xJw4jpsQAzhqy8//EAB4RAQEBAQEAAwEBAQAAAAAAAAEAESExEEFRgaHB/9oACAEDAQE/EHyw8tXqS5uNme2o46wvYw5dln20fLj6s55C+iKVykGWNtld6yA2LBjv7/n19xk8YctSXlsvUJkPPfjCY+SAIPQdfznh/YooQ9Nz/mxyTew7rafGQmwvpDPLEoMYmvpCVP7G8hG62E/US9+W/wBkpbYzW/ADxlbJO2F7He/GQRLS2WxcyeqI4sPL/8QAHhEBAQEAAwEBAAMAAAAAAAAAAQARECExQSBRYZH/2gAIAQIBAT8Q5ZD5JF3Z+m0lLSd5+AC/IV2S9VmQUXy3IyfGCE+Wcaiq7q+r0f79idMG+QZPe3j2Ry1+WrH+LuIXO/Yj3A72BSV3IMtBvOFnQmeJ7LR3L+ixbSPRGBxtrgODuNnsAFvUdhx//8QAJhABAAICAQQCAgMBAQAAAAAAAQARITFBUWFxgZGhscEQ0fDh8f/aAAgBAQABPxDIziJ0Qq7LxHTVpxATAZ4NYlEBXay1B2HECKOclzBy8m4DI9kUBRdkB8I5jOm3qEzQyeICLGluOZRQtRLmJ1xBcwb1NZVHVgqWuhhWjfVGabM1RNiqtS90CNAXcCuDOVzMFQ4JuaB10lY5tnEcaqueZfFahA6LVwBwNMMrLhmcq4KsxFZOZvTOZeZnyECBUEuMFdYFeFS1QvapVVKpkWT3ihGPUXaZhsWdEDjtpsj5sp3BziLMdlxcTW130l7oupxAxR4EipxceiqjhQIWCkMysqusRGQjOhBApIgrylRzAhENK0UWq27oooy3gr29w1oK7sJVIZmheYFBRI44jVylAuBbDuY4GVNGIXSFtL4hqqBVVCDRBFdyaI7y2sFCgp9QD6iqNy4R4VTxzERFiytSycxlV/WYzhLPErHbVVWgrED/AG1RDlgvvdwnNa3wKlvEwrWSXPktiVLaJOHMAgWU1/5CVxG2dBcLASwAESRdKmVUBt0la5VxApl7hNx2XviA2AIm9nF1DVku8g5m30UpcBiyF8XxuMNwdG1kGL3dqxUtrWRA0FRYcABypMQDksxA3Stq0K63cRwt2MZlFAFsl57w1bwiQZ8I+0YH4gq6XlnxxiMUkuOABu4vh1xC8JdBCZWKe+ALKuoq8fhT8S0OxZb4yMx8Kpz14XG5bfFI+Q1EG4tWTwxoYYEX8TLi6uI7TI9WQwXS+I+5jueVTM7Rwv3Fnu0TlMHnXBxXEWm6Cye3EQLMOQAzs5m66LbVA7Y1mxcgqAXdQxajk0W1FKyoSIpIFjcwtY9i5Xbc1JsmURoo3TpKmYM5mU23lvllvMCD3n9ka6ItoJlBGvmDaaWB5tL9IY0BkDzwy5GN0SuhDiPCPyIHCSlTdJZDlqxPytrCffQRfaYWA3Zn0l3oFCesKMvlV+CLyq6QCe6JSSV3D5eCCDnKdrm0RjjKaKO6lj3KEbfIps91V8S/VCSdAUAEBtdawwzVYIB6ROWldjcQHQwoEKjQzWSn1GOgwYu9nOItJejHZt0fYQYa6MsdtuJ1V4qveLhYAWD5uoqaKB/kKmS41Zl3EB6Y0L9j7EFjgV3hwvqJFDhsywqzYcSlOMH3FQnsWMnxGGmF8rCGw+IfoOEerPuG6A38mAS8UhZmnpZKt1w0eMh7UQMtUoSALbzZarlZh+2PEA6aBYOqcSrcHbE1+1CoUIFy2IdXBxeVbf37kcKClMfXKYfRosOqY0GrowvUrvLDfdFteIDSj2M+Jcw0YRmAvAhUfqFq0vIxQTjQMl7ETakeaUXFsI79RXfIH1Fi6T90BMcqcnekjCulUzlFUFbYTguRC1jq0V5JgLpwuJccK2yXQ7qvSP8AHEsGC6VvdOyN6f0Z4sAACpD0QuWTKIrICgPUXKkjjOBAqgj5uZnjhv4IyROxe2AQJ3Q/TcFQthQFeqIoLDsATIZ1wBB0bT6ieaWwJVRpy+oroo84gBRtV/4j6qt0h/3GzJxR6C16jIqIBJjVFXQllV4zKP0VvRcN0CXumhcKX8WWj1r1MPn7i9irRQKg9V1ykaBypnjsecmD3DwEEbOcPuXN1zFNAeYK2XVmgoSuCC622YDaIzlAtjgVhACQjxtFoBst9z0T2Xp5igvggnfATuSz8sofaiNSijAogcOeEZZctysBX6JtGvtDqMzJAXYCOVnkQCywYwtaUYLruYYzecGNDs/D7ZnjgIrK0VZSVmzeJaqMrbPzKq1mlpGaUryf9xBk14s/uXoK/wCBmU7n3ccDRdJZ7lXp11IS6Uewmwh0KnnMRrVA/wBgD2kQhulku5Z9y6GF0BXlD7gcJ8TxQuuXpcKN8bwjdQ+UZWKVYGd/6ksELNlr4lqBPmdPaWNeIiHm1nH1CXs1kqVf2UEqQrlufliHTjrZ+Yhbq8NaQKdjiwl3nPYGoL6+BEdAsyRIPm9liNilyGcNWDoRdn4j4/kLomnpNjxNPCfqTd4m3i/lht4P3Ptz8T+J/h9Z/l9f4l/x+Z+80+E/Gfw6E//Z",
  "coverImageMobileThumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAQCAwMDAgQDAwMEBAQEBQkGBQUFBQsICAYJDQsNDQ0LDAwOEBQRDg8TDwwMEhgSExUWFxcXDhEZGxkWGhQWFxb/2wBDAQQEBAUFBQoGBgoWDwwPFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhb/wgARCABDAC0DASIAAhEBAxEB/8QAGwAAAQUBAQAAAAAAAAAAAAAABAABAwUGBwL/xAAYAQEBAQEBAAAAAAAAAAAAAAACAQMABP/aAAwDAQACEAMQAAAB4rJEt/CQ8Dw+4382nv0W4i5NH3XNxcufSRlEWmSl0zvxKQA6XQ4kpYeowGy3yLFs5ONOHowpas9JGb2l3GeEmP/EACQQAAICAQQCAQUAAAAAAAAAAAIDAQQABRESIRAUExUjMUFC/9oACAEBAAEFAoyA3whgY62Lac2jOvHLrfx1hI3xaJk/VbGSkhn4t5aoYwKsTX+x7BVbRjNO5ZOzp1xBei1q61hzjty6vOoa3BKnU7zENOuwSYjas9vrfLzJw0+P8hyxhZpTgW7Qq3GvY0wzb9JLDpQGXFCt495ScwUi085zkn1YrlZlcRvGfjP0pYTkqDl//8QAGhEAAwEBAQEAAAAAAAAAAAAAAAERAhAhMf/aAAgBAwEBPwHiFH6QSRhRTmRlYtT71n//xAAbEQACAwADAAAAAAAAAAAAAAABEAACESAhUf/aAAgBAgEBPwFlHZcd6isENfOH/8QANBAAAgIBAwAFBw0AAAAAAAAAAQIAAxIRITEEE0FRcSAiMmGRocEFEBQjJDM0QnKBgrHw/9oACAEBAAY/ApzOfL0+fVSv6R2TSaGszRkImmkGx9sW+lm6w26Oa0G0GXyncrj8jFJ1j9LOg9DFU38YysKmZdwSAFjB+jDxDa6RXRqP5XARR0ewV8dYlbsikxba3WvbzsWLMf3xgqrqRwB6bZZazRW6vHlsgCZm91zXHnKv46wdZRke/PH4Q31WtWUP1uG2vrn2jpl1mvBVstffDhfcW7jWNP7nbODBusIt+7dSG8P98JdVffYi5+bgoOvr3jN9KUg8FhvPxKeybvl4NDWhZsech2zSKncJxORORA9bIGGzZdvdOB5G498498//xAAjEAEAAgICAgIDAQEAAAAAAAABABEhMUFRcaFhsYGRwdHw/9oACAEBAAE/IfSXNYIW96qCuldwB1Pk9xeE+RY2okMdtxTzHE3A/OgftuDHzppqLkR4l+BqcgwSnVY5jvhPDMOexE8ytGPCHmnceNrdAdLVmXC0ybfO4mAOhj2lxATN2PhlStCDBxxjDHtRg8XPCWKYL0dhsgMbF+6+42KOhT/x1CAnU+q0p8JSyDrGtP2QVVMNYPn0mEkNNbyfzFK5TWb/AJKm+HPEt+F5i17C5Rk/Xsh6oEeK3g6XjUtwjoXzWJQ17sb52BcR/U0fO7E5GJdU3L+XWVdxRGe6al2eX4g6xz+G2+sfif41CFUS9DAzvmUtmu0Kz7p//9oADAMBAAIAAwAAABBJHBHlNOlqr4l14D//xAAaEQEBAQEBAQEAAAAAAAAAAAABABEhMRBh/9oACAEDAQE/EExk/IciIPGwcyw9LCmKPIczY4Z8jUfZvTf/xAAZEQEBAAMBAAAAAAAAAAAAAAABABExQSH/2gAIAQIBAT8QRsPYkijDm0YkYA5c+XrFZyEbjV//xAAhEAEBAAICAwEAAwEAAAAAAAABEQAhMUFRYYFxodHwkf/aAAgBAQABPxA1oxPjgwbTu9ONrPqOBQRUidvrN1BBUus1jGICU7Hv/esWIAh/3JSwtnjLFPs8mBEjZN9YNDKD4UOSc1LXm89GC4a1LNfnzOriDy/PebsDomr+5Fd0oG8dJjTKuG4JjjRBEmlIxlTPJZkNooPJmlgHuDgIrxl9KQtXCI2eALgEoUwLyJw/crnObU2WE+5c3kwsRu8QSgEOAzTcFb3cGY3aXeG/yqH4aF+ZQXREJoBiPjhMsIWvsJ+4ACR2KP8AC3B0plRg21RB2G/rHoRDAEMd4ixhiOXadj+OlEPZ8ZYnaAZ/TBBtMKQe83svQF9XC8gTsSH9tJ7nWUmcXF9gOweQ86wS7cEnonczlMhKJtimX0m6YSLYhu8fxvUwzCV2Jp77yKStgGcWqVAhwb0eMcDQ8Hn+cJlU0K0/nOLp+6/M2QSyRoOm+T8veGEDfhk0AX+sVDvIB5yUpTrauJp23AePD7cISntO08+jP//Z"
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
coverImageUrlstringURL to the main image, displayed in background when starter site is opened.
coverImageThumbnailbase64Thumbnail cover image.
coverImageMobileUrlstringURL to the main image, displayed in background when starter site is opened on mobiles.
coverImageMobileThumbnailbase64Thumbnail cover image for mobile devices

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
422The uploaded file is not an image
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload owner portrait

Upload starter site owner portrait. The image itself is to be placed in the request body.

Request example

POST /api/v3/4870020/startersite/ownerportrait?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/startersite/ownerportrait?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/startersite/ownerportrait?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/startersite/ownerportrait?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

When uploading a starter site owner portrait, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
  "meetownerownerimageurl": "https://s3.amazonaws.com/images.ecwid.com/startersite/images/1003/1468931549471.jpg"
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

NameTypeDescription
meetownerownerimageurlstringURL to owner photo in the “About owner” section

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
415Unsupported content-type: expected application/octet-stream
422The uploaded file is not an image
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload quote person image

Upload starter site quote person image. The image itself is to be placed in the request body.

Request example

POST /api/v3/4870020/startersite/quoteperson?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/startersite/quoteperson?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/startersite/quoteperson?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/startersite/quoteperson?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

When uploading a starter site owner portrait, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Response

Response example

{
  "quotepersonimageurl": "https://s3.amazonaws.com/images.ecwid.com/startersite/images/1003/1468931800030.jpg"
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

NameTypeDescription
quotepersonimageurlstringURL to a photo of a customer with testimonial

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
415Unsupported content-type: expected application/octet-stream
422The uploaded file is not an image
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Webhooks

Overview

Webhooks

Basically, a webhook is an HTTP POST request that occurs when something happens. In other words, it’s a simple event notification via HTTP POST. Ecwid uses webhooks to notify your application in real time about events in the merchant store.

This is how your application can use webhooks:

  • Receive a request from Ecwid every time a new product is created or an existing product is changed so you can synchronize the store catalog with your local database. Get the updated product data and make your app in sync in one HTTP request instead of downloading the whole catalog.
  • Get notified about every new order in the store so you can send a custom email or text message, generate a custom receipt, or subscribe the customer to your newsletter.

How it works in Ecwid

In a nutshell, webhooks in Ecwid work this way:

  • Ecwid will use the Webhook URL from your application details to send webhooks there
  • When a user (merchant) installs your application, the webhooks for this store are automatically enabled
  • Each supported event in the store (e.g. new order is placed) triggers an HTTP POST request to the URL your specified
  • Your application receives the requests and replies with 200 OK to identify that it’s received
  • Then your app processes the webhook request and performs further steps to handle the event

Supported events

The following events are supported:

Orders

  • New order was placed
  • Order was updated
  • Order was deleted
  • Unfinished order was created
  • Unfinished order was updated
  • Unfinished order was deleted

order.updated and unfinished_order.updated events are triggered when any changes are made to an unfinished or completed order. Orders endpoint allows you to control and get information about unfinished and completed orders in a store.

Products

  • New product was created
  • Product was updated
  • Product was deleted

product.updated events are triggered when any part of a product is updated: quantity, categories assigned, product options, combinations, attributes, images, pricing, etc. Products endpoint allows you to control and get information about products in a store.

Application

  • Application was installed
  • Application status was updated
  • Application was deleted

Application endpoint allows you to check status of your application.

Setting up webhooks

Setup process is easy. Once your application has a webhook URL specified in the settings and has a token with appropriate access level for the store, it will receive notifications automatically. More details on these are below.

1. Set webhook URL

After you successfully registered your application with Ecwid, please contact us and provide a webhook URL – Ecwid will send a request to this URL each time a supported event occurs. To enable or modify webhooks for existing application, please contact us as well.

2. Set webhook events

There are several types of events in the store that Ecwid can notify your application about, check out Event type section of webhook structure for more details.

Please specify the exact event types you wish to be notified about upon registering your application or contact us if you already have an app.

3. Set custom HTTP headers (optional)

You are also able to specify your custom HTTP headers to be provided by Ecwid when sending webhooks to your URL. If you want to add custom headers to your app, please contact us. Learn more about custom HTTP headers

4. Get access

Each application has scope of access that controls the set of store resources and operations permitted for the application. The same set of access scopes is used to determine which events your application can be notified of. To be notified of the product updates, make sure your app has read_catalog access to the store. The read_orders scope allows to get order webhooks. See Access scopes for more details.

Webhook structure

Webhook request body

Webhook header example

POST https://www.myapp.com/callback?eventType=order.updated HTTP/1.1
Host: www.myapp.com
Content-Type: application/json; charset=UTF-8
Content-Length: 243
Cache-Control: no-cache
X-Ecwid-Webhook-Signature: MeV28XtFal4HCkYFvdilwckJinc6Dtp4ZWpPhm/pzd4=

Unfinished order #105 created webhook body example

{
  "eventId":"123456-1234-1234-1234-123412341234",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":105, // this is the number of the unfinished order
  "eventType":"unfinished_order.created"
}

Unfinished order #105 updated webhook body example

{
  "eventId":