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. Requires read_orders scope to function
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.

If your application is installed on a device (mobile, desktop, etc.) we suggest using a deep link to your app as a redirect_uri. Deep linking allows applications to direct user to a specific page within the application, just like a regular URL on the Internet. Learn more about deep linking and how to enable it in your application.

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.

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

To protect us and our users from abusing, we strongly advise that you optimize your app code to make fewer API requests. For example:

  • Cache store data locally if you need to use or display it many times in your app
  • If you need to synchronize store data with your database, use Webhooks to get timely updates about changes in a store. More details: Webhooks – To get multiple product details at once (knowing their productIds), specify them in a corresponding filter – productId. More details: Searching Products
  • To get multiple order details at once (knowing their orderNumbers), specify them in a corresponding filter – orderNumber. More details: Searching Orders

We constantly monitor API activity and servers load on our side to make sure every application uses API properly. In case an app abuses Ecwid API by generating huge amount of requests every day, we’ll 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

Using the endpoints below you can get and update basic Ecwid store information like store name, merchant’s email, company address, logos and more.

Get store profile

Get basic information about an Ecwid store: settings, store location, email, etc. This request is available with any access token.

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

Update basic store information in an Ecwid store: settings, store location, email, etc.

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",
    "abandonedSalesUpdated": "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
abandonedSalesUpdatedstringDate of the latest changes to abandoned carts in a store, 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

Using the methods below you can search/create/modify/delete products in an Ecwid store. In the Ecwid Help Center you can learn more about the products in Ecwid.

Search products

Search or filter products in a store catalog. The response provides full details of found 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. To get Store Front Page products, specify &category=0 in the request
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 options and 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 will be displayed on the 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
showOnFrontpagenumberA positive number indicates the position (index) of a product in the store front page – the smaller the number, the higher the product is displayed on a page. A negative value means the 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

Get all details of a specific product in an Ecwid store by its ID.

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 options and 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 will be displayed on the 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
showOnFrontpagenumberA positive number indicates the position (index) of a product in the store front page – the smaller the number, the higher the product is displayed on a page. A negative value means the 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

Create a new product in an Ecwid store.

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 will be displayed on the 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
showOnFrontpagenumberA positive number indicates the position (index) of a product in the store front page – the smaller the number, the higher the product is displayed on a page. A negative value means the product is not shown in the store front page. If no categories are assigned to product in categoryIds field, the showOnFrontPage will be 1

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

Update an existing product in an Ecwid store referring to its ID.

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 will be displayed on the 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
showOnFrontpagenumberA positive number indicates the position (index) of a product in the store front page – the smaller the number, the higher the product is displayed on a page. A negative value means the 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
400Attribute showOnFrontpage was specified as a negative number when there are no categories assigned to productAttribute showOnFrontpage can’t be negative, because the product has no categories
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

Delete a product from an Ecwid store referring to its ID.

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

Delete the main image of a product in an Ecwid store.

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

Delete an image from a product gallery in an Ecwid store.

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

Remove all gallery images attached to the product

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

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 referring to its 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

Upload a file to a product in an Ecwid store (E-goods).

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)

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 file itself needs to be sent in the body of your request in a form of binary data. The file 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

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

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"
}

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

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

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 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

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

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

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

Using the methods below you can search/get/update/delete categories in an Ecwid store. It is possible to change the category name, its products, image and more.

Get categories

Search or filter categories in a store catalog. The response provides basic details of found categories.

The order of categories in response sometimes does not represent their order in the Ecwid Control Panel or storefront. To have categories in that order, check the orderBy field value for each category returned by Ecwid and use it as a sort index in your application.

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

Get full category details from an Ecwid store referring to its ID.

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

Create a new category in an Ecwid store catalog.

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

Update an existing category in an Ecwid store referring to its ID.

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

Delete a category in an Ecwid store referring to its ID.

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

Delete the category image from an Ecwid store.

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

Using the methods below you can get/update/delete combinations and their details in an Ecwid store. Learn more about product combinations in the Ecwid Help Center.

Get all product combinations

Get all combinations of a specific product in an Ecwid store.

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

Get a specific product combination details referring to its ID.

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

Update a specific product combination details referring to its ID.

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

Delete a specific product combination referring to its ID.

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

Delete all product combinations of a product in an Ecwid store.

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

Upload a custom image for a specific product combination referring to its ID.

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

Delete an image of a specific product combination in an Ecwid store.

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

Get all product types present in an Ecwid store.

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

Get the full details of a specific product type referring to its ID.

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

Update the details of a specific product type referring to its ID.

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

Create a new product type in an Ecwid store.

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

Delete a specific 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

The endpoints below allow you to search/create/update/delete orders in an Ecwid store. Learn more about orders in Ecwid in our Help Center.

Search orders

Search or filter orders in an Ecwid store. The response provides full details of the found 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. Also, check out the carts endpoint methods for additional info.

Coming soon: Abandoned sales will not have an orderNumber or vendorOrderNumber assigned to them. Instead, they will have a unique order id in orderNumber and vendorOrderNumber field.

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: 100
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(s) separated by a comma. If this field is not empty, other filters are ignored
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
orderNumbernumberUnique order number without prefixes/suffixes, e.g. 34. COMING SOON: For completed orders orderNumber will work as usual. For abandoned sales i.e. the paymentStatus is INCOMPLETE, orderNumber will be a unique order ID.
vendorOrderNumberstringOrder number with prefix and suffix defined by admin, e.g. ABC34-q. COMING SOON: For completed orders, vendorOrderNumber will work as usual. For abandoned sales i.e. the paymentStatus is INCOMPLETE, vendorOrderNumber will be a unique order ID.
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
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
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
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

Get all available information about an order referring to its ID. The order details include: customer email, payment/shipping method, items purchased and more.

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

When you know the exact order numbers for orders you need, you can get those order details in one request (batch request). To do that, use the Search orders method: provide the order numbers you have in the orderNumber 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 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
orderNumbernumberUnique order number without prefixes/suffixes, e.g. 34. COMING SOON: For completed orders orderNumber will work as usual. For abandoned sales i.e. the paymentStatus is INCOMPLETE, orderNumber will be a unique order ID.
vendorOrderNumberstringOrder number with prefix and suffix defined by admin, e.g. ABC34-q. COMING SOON: For completed orders, vendorOrderNumber will work as usual. For abandoned sales i.e. the paymentStatus is INCOMPLETE, vendorOrderNumber will be a unique order ID.
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
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
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
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 HTML code of an invoice for a specific order placed in an Ecwid 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 an Ecwid 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 for completed orders. Coming soon: you can also use order id you got from the order details in the orderNumber field for abandoned sales (paymentStatus == INCOMPLETE).

Request body

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

Order

FieldTypeDescription
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
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
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
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
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

Delete a specific order in an Ecwid store referrint to its ID.

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

Create a new order in an Ecwid store. This can be useful for storefronts with a custom checkout process or manually creating orders for sales made earlier.

Request body

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

Order

FieldTypeDescription
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
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
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
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

Customers can attach files to product options when adding products to cart. Using this method, you can remove that file from an order.

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

Carts

When a customer leaves an online store without making a purchase it is recorded as an abandoned cart in Ecwid. The methods below describe how you can search for abandoned carts, place them as completed orders or update its contents. Learn more about abandoned carts in the Ecwid Help Center.

You can also calculate the order total and available shipping methods using the special endpoint in the Ecwid API. It is useful for storefronts with a custom checkout process.

Search abandoned carts

Search for abandoned carts in an Ecwid stores and filter the results by create/update date, customer, order total.

Request example

GET /api/v3/4870020/carts?customer=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}/carts?showHidden={showHidden}&totalFrom={totalFrom}&totalTo={totalTo}&createdFrom={createdFrom}&createdTo={createdTo}&updatedFrom={updatedFrom}&updatedTo={updatedTo}&couponCode={couponCode}&customer={customer}&offset={offset}&limit={limit}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
showHiddenbooleanIf true Ecwid will show all abandoned carts found, even if store owner deleted them in the Ecwid Control Panel. If false, the response will provide abandoned carts with hidden field as false only. If not specified, the filter is set to true
totalFromnumberMinimum product price
totalTonumberMaximum product price
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
couponCodenumberThe code of coupon applied to order
customerstringCustomer search term. Searches for customer details in order, except for customerId
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 100

Response

Response example (JSON)

{
    "total": 1,
    "count": 1,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            // Basic information
            "cartId": "6626E60A-A6F9-4CD5-8230-43D5F162E0CD",
            "tax": 1.79,
            "subtotal": 29.95,
            "total": 37.39,
            "usdTotal": 37.39,
            "paymentMethod": "Purchase order",

            // 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",

            // 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"
            },
            "recovered_order_id": 1231245,
            "recovery_email_sent_timestamp": "1427272209"
        }
    ]
}

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
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
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
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
recovered_order_idstringInternal order ID. Is present if the abandoned cart was successfully recovered
recovery_email_sent_timestampstringUNIX timestamp of a date when abandoned cart recovery email was sent to customer

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
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
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 abandoned cart

Get details of an abandoned cart using its unique cart ID.

Request example

GET /api/v3/4870020/carts/6626E60A-A6F9-4CD5-8230-43D5F162E0CD?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}/carts/{cartId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
cartIdstringUnique abandoned cart identifier. To get a correct response, the value must completely match the record in Ecwid

Response

Response example (JSON)

{
    "total": 1,
    "count": 1,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            // Basic information
            "cartId": "6626E60A-A6F9-4CD5-8230-43D5F162E0CD",
            "tax": 1.79,
            "subtotal": 29.95,
            "total": 37.39,
            "usdTotal": 37.39,
            "paymentMethod": "Purchase order",

            // 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",

            // 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"
            },
            "recovered_order_id": 1231245,
            "recovery_email_sent_timestamp": "1427272209"
        }
    ]
}

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

OrderEntry

FieldTypeDescription
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
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
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
recovered_order_idstringInternal order ID. Is present if the abandoned cart was successfully recovered
recovery_email_sent_timestampstringUNIX timestamp of a date when abandoned cart recovery email was sent to customer

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
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
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

Update abandoned cart

Update the details of specific abandoned cart using its unique cart ID.

Request example

PUT /api/v3/4870020/carts/6626E60A-A6F9-4CD5-8230-43D5F162E0CD?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

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

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
cartIdstringUnique abandoned cart identifier

Response

Response example (JSON)

{
  "hidden": true
}

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

Order

FieldTypeDescription
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.

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

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

Convert abandoned cart to order

Request example

POST /api/v3/4870020/carts/6626E60A-A6F9-4CD5-8230-43D5F162E0CD/place?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

Converts the abandoned cart into a completed order in an Ecwid store.

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

Request body

Request body is empty for this endpoint.

Response

Response example (JSON)

{
  "orderNumber": 829,
  "vendorOrderNumber": "000008292017"
}

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

CreateStatus

FieldTypeDescription
orderNumbernumberUnique order number without prefixes/suffixes, e.g. 34
vendorOrderNumberstringOrder number with prefix and suffix defined by admin, e.g. ABC34-q

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

Customers

It is possible to place orders without creating an account in a store – it depends on the store settings. Using the methods below you can get information about registered customers and modify them.

Search customers

Search for customers by a keyword or basic filters: number of orders made, name, email, customer group and more.

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

Get full customers details referring to their ID in an Ecwid store.

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

Create a new customer in an Ecwid store.

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

Update details of an existing customer in an Ecwid store.

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

Delete a specific customer from an Ecwid store referring to their ID.

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

Get information about all customer groups in an Ecwid store.

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

Get information about a specific customer group in an Ecwid store referring to its ID.

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

Create a brand new customer group in an Ecwid store.

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

Update an existing customer group in an Ecwid store referring to its ID.

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

Delete a customer group in an Ecwid store referring to its ID.

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

Discount coupons allow customers to get discounts on their orders in the checkout process. For store owners it’s a great way to increase sales or make a temporary promotion.

Learn more about discount coupons in our Help Center.

Search coupons

Search or filter discount coupons in an Ecwid store. Filters include: discount coupon code, type, availability.

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",