Product API
The Ecwid Product API provides a RESTful interface with JSON-formatted responses to get information about enabled products, categories and some settings of a particular Ecwid store.
You can use this API to show your store's products in a different place, create the "Featured products" or "Bestsellers" mods for your CMS, create custom menus with Ecwid categories, and much more.
This document provides information to developers on how to integrate with the Ecwid API.
Authentication
No authentication or API keys are needed to access the Product API. However only paid Ecwid accounts have Product API enabled.
HTTP Requests
The Ecwid Product API uses a RESTful calling style that works with standard HTTP GET requests. Any web programming language (PHP, Ruby, Perl, Python, Java, etc) should be able to make and receive such calls.
HTTP Response Codes and Errors
The Product API uses standard HTTP status codes to indicate success or failure of API calls. See the section Standard Response Codes for a description of the codes used and their meaning.
Rate Limiting
The default rate limit per IP for calls to the REST API is 100 requests per 5 seconds, 400 requests in 50 seconds, 1400 requests in 500 seconds.
No more than 10 simultaneous connections from one IP
Encoding and Response
Response data is JSON-encoded. JSON is a lightweight data serialization language that is compatible with many languages.
The charset of all responses is UTF-8.
If a user-agent specifies 'gzip' as one of the possible content encodings in a 'Accept-Encoding' HTTP header field, then the reply is compressed and 'Content-encoding: gzip' header is set.
Only 'enabled' products and categories are returned by the REST API. Those are products and categories visible for customers. You can change visibility in your control panel.
JSONP support
Ecwid Product API can optionally respond with JSONP format. JSONP is basically the same as JSON, the only difference is that the resulting dataset of any request will be wrapped with a function call. You can specify the name of the function to call with an additional 'callback' parameter. This parameter can be used for all Product API methods, so it is omitted from the method parameters described below - just assume you can always use an additional callback parameter on any of the below methods.
If you are using the popular jQuery library and would like to make the Product API calls from your webpage via AJAX, you can use jQuery's getJSON utility method and append '&callback=?' to the URLs of Product API methods (described below) to simultaneously switch both jQuery and Ecwid Product API to the JSONP mode.
REST API Methods
REST API Method: categories
Returns an array of immediate subcategories of a given parent category. If the parent parameter is absent, returns all categories. If parent=0, returns a list of root categories. Disabled categories are not returned, but enabled subcategories of disabled categories are.
URL
http://app.ecwid.com/api/v1/STOREID/categories?parent=CATEGORYID
Format
JSON
HTTP Method
GET
Parameters
STOREID
|
Required |
ID of the Ecwid store
|
parent
|
Optional
|
ID of a parent category. If the parent parameter is absent, returns all categories. If parent=0, returns a list of root categories. |
Response (about return values)
Array of <Category> objects. This object represents full information on a category:
Field name
|
Type
|
Description
|
id
|
Integer
|
A unique integer category ID.
|
parentId
|
Integer
|
An ID of the parent category, if any. This key is absent for root categories.
|
thumbnailUrl
|
URL
|
If present, an URL of a category thumbnail (usually 160x160).
|
name
|
Plain text
|
Category name.
|
|
url
|
URL |
URL of the category. |
| description |
HTML |
Category description |
REST API Method: products
Returns an array of products of a given category. If the category parameter is absent, returns all products. If category=0, then returns a list of products which are not assigned to any category. Disabled products are not returned.
URL
http://app.ecwid.com/api/v1/STOREID/products?category=CATEGORYID
Format
JSON
HTTP Method
GET
Parameters
STOREID
|
Required |
ID of the Ecwid store
|
category
|
Optional
|
ID of a parent category. If the category parameter is absent, returns all products. If category=0, then returns a list of products which are not assigned to any category.
|
Response (about return values)
Array of <ProductEntry> objects. This object represents information on a product:
Field name
|
Type
|
Description
|
id
|
Integer
|
A unique integer product ID. Not to be confused with the product SKU, which is a separate field.
|
sku
|
Plain text
|
Product SKU, that is, a unique code
|
smallThumbnailUrl
|
URL
|
If present, an URL of a small product thumbnail (usually 80x80).
|
thumbnailUrl
|
URL
|
If present, an URL of a product thumbnail (usually 160x160).
|
imageUrl
|
URL
|
If present, an URL of a product image, usually no more then 500x500.
|
quantity
|
Integer
|
Amount of the product in stock. Absent for unlimited products.
|
name
|
Plain text
|
Product name.
|
price
|
Double
|
Product price.
|
weight
|
Double
|
If present, specifies the product weight, in the store units. Absent for intangible products.
|
| url |
URL
|
URL of the product
|
| defaultCombination |
ProductCombination |
If present, a default product combination |
REST API Method: product
Returns a product information by a product ID.
URL
http://app.ecwid.com/api/v1/STOREID/product?id=PRODUCTID
Format
JSON
HTTP Method
GET
Parameters
STOREID
|
Required |
ID of the Ecwid store |
| product |
Required
|
ID of a necessary product |
Response (about return values):
Returns a <Product> object. This object represents full information on a product: all fields of the ProductEntry plus some additional fields.
<Product> object
Field name
|
Type
|
Description
|
id
|
Integer
|
A unique integer product ID. Not to be confused with the product SKU, which is a separate field.
|
sku
|
Plain text
|
Product SKU, that is, a unique code
|
smallThumbnailUrl
|
URL
|
If present, an URL of a small product thumbnail (usually 80x80).
|
thumbnailUrl
|
URL
|
If present, an URL of a product thumbnail (usually 160x160).
|
imageUrl
|
URL
|
If present, an URL of a product image, usually no more than 500x500.
|
quantity
|
Integer
|
Amount of the product in stock. Absent for unlimited products.
|
name
|
Plain text
|
Product name.
|
price
|
Double
|
Product price.
|
weight
|
Double
|
If present, specifies the product weight, in the store units. Absent for intangible products.
|
| url |
URL
|
URL of the product
|
description
|
HTML
|
Product description (optional).
|
options
|
Array<ProductOption>
|
A list of the product options. Empty if no options are specified for the product.
|
taxes
|
Array<ProductTax>
|
A list of included taxes.
|
galleryImages
|
Array<GalleryImage>
|
A list of gallery images.
|
| categories |
Array<Category> |
A list of categories which this product belongs to |
| dateAdded |
Integer |
Product creation date (UNIX timestamp).
Note: this field is obsolete and will be removed in a future version of API. Use "created" field instead.
|
| created |
Date |
Product creation date |
| defaultCombinationId |
Integer |
If present, unique ID for default product combination |
| combinations |
Array<ProductCombination> |
If present, list of product combinations |
<ProductOption>
Field name
|
Type
|
Description
|
name
|
Plain text
|
Option name, like 'Color'.
|
type
|
Plain text
|
One of 'SELECT', 'RADIO', 'TEXTFIELD', 'TEXTAREA', 'DATE', 'FILES'.
|
choices
|
Array<ProductOptionChoice>
|
All possible option choices, if the type is 'SELECT' or 'RADIO'. Absent otherwise.
|
defaultChoice
|
Integer
|
The number, starting from 0, of the default choice. Only present if the type is 'SELECT' or 'RADIO'.
|
| required |
Boolean |
"true" if this option is required, "false" otherwise |
<ProductOptionChoice>
Field name
|
Type
|
Description
|
text
|
Plain text
|
A text displayed as a choice in a drop-down or a radio box, e.g. 'Green'.
|
priceModifierType
|
Plain text
|
Specifies the way the product price is modified. One of 'PERCENT' or 'ABSOLUTE'. If 'PERCENT', then priceModifier is a number of percents to add to the price. If 'ABSOLUTE', then priceModifier is a number of currency units to add to the price.
|
priceModifier
|
Double
|
Number of percents or currency units to add to the product price when this choice is selected. May be negative or zero.
|
sku
|
Plain text
|
SKU prefix to add to the product's SKU to obtain the full SKU of the option combination. This is optional.
|
<ProductTax>
Field name
|
Type
|
Description
|
name
|
Plain text
|
The tax display name, e.g. 'VAT'.
|
value
|
Double
|
The tax value, in store currency.
|
<GalleryImage>
Field name
|
Type
|
Description
|
alt
|
Plain text
|
The image description, displayed in 'alt' image attribute.
|
url
|
URL
|
The image url.
|
width
|
Integer
|
Width of the image.
|
height
|
Integer
|
Height of the image.
|
| thumbnail |
URL
|
An URL of the image thumbnail with dimensions 46x42.
|
<ProductCombination>
Field name
|
Type
|
Description
|
id
|
Integer
|
A unique integer combination ID
|
| sku |
String |
If present, combination SKU, unique code |
smallThumbnailUrl
|
URL
|
If present, URL of a small combination thumbnail (usually 80x80). |
thumbnailUrl
|
URL
|
If present, URL of a combination thumbnail (usually 160x160).
|
imageUrl
|
URL
|
If present, URL of a combination image, usually no more than 500x500.
|
quantity
|
Integer
|
Amount of the combination in stock. Absent for unlimited combinations.
|
price
|
Double
|
Combination price
|
weight
|
Double
|
If present, specifies the combination weight, in the store units. Absent for intangible combinations.
|
| options |
Map<String, ProductOptionChoice> |
Set of options which identifies this combination |
REST API Method: profile
Returns a general information about a store.
URL
http://app.ecwid.com/api/v1/STOREID/profile
Format
JSON
HTTP Method
GET
Parameters
STOREID
|
Required |
ID of the Ecwid store |
Response (about return values):
Returns a <Profile> object.
Field name
|
Type
|
Description
|
storeName
|
Plain text
|
The store name
|
storeUrl
|
URL
|
Store url
|
weightUnit
|
Plain text
|
Weight unit used in store. Possible values: CARAT, GRAM, OUNCE, POUND, KILOGRAM
|
currency
|
Plain text
|
Currency code, used in this store ('USD', 'CAD' etc)
|
|
currencyPrefix
|
Plain text
|
Prefix of the currency symbol |
| currencySuffix |
Plain text
|
Suffix of the currency symbol |
| groupSeparator |
Plain text |
A thousands separator. Possible values: space, dot(".") or comma (","). |
| decimalSeparator |
Plain text |
A symbol used in the store to mark the boundary between the integral and the fractional parts in prices. Possible values: dot or comma, For example "." for $59.99 or "," for "34,50руб".
|
| numericPrecision |
Integer |
Numbers of digits in the store price`s fractional part. Usually 2($2.99) or 0 (¥500) |
| closed |
boolean |
'true' if the store is closed for maintenance and 'false' if it is open. |
| mobileUrl |
Plain text
|
The URL of the mobile version of the store (since Ecwid version 10.2) |
REST API Method: random_products
Returns an array of random products of a store.
URL
http://app.ecwid.com/api/v1/STOREID/random_products?count=NUMBER_OF_PRODUCTS
Format
JSON
HTTP Method
GET
Parameters
STOREID
|
Required |
ID of the Ecwid store
|
count
|
Required
|
Integer number of random products to return.
|
Response (about return values)
Array of <ProductEntry> objects. This object represents information on a product:
Field name
|
Type
|
Description
|
id
|
Integer
|
A unique integer product ID. Not to be confused with the product SKU, which is a separate field.
|
sku
|
Plain text
|
Product SKU, that is, a unique code
|
smallThumbnailUrl
|
URL
|
If present, an URL of a small product thumbnail (usually 80x80).
|
thumbnailUrl
|
URL
|
If present, an URL of a product thumbnail (usually 160x160).
|
imageUrl
|
URL
|
If present, an URL of a product image, usually no more then 500x500.
|
quantity
|
Integer
|
Amount of the product in stock. Absent for unlimited products.
|
name
|
Plain text
|
Product name.
|
price
|
Double
|
Product price. This price contains included taxes.
|
weight
|
Double
|
If present, specifies the product weight, in the store units. Absent for intangible products.
|
| url |
URL
|
URL of the product
|
| defaultCombination |
ProductCombination |
If present, a default product combination |
REST API Method: batch
Batches several queries in one HTTP request. Queries are URL parts just after STOREID, without any leading '/', like 'product?product=123'. Keys are arbitrary strings used to identify the query request in a HTTP response. The returning value is a JSON map, containing all query results for the corresponding keys. One batch request can not contain more than 15 unique queries or more than 100 any queries at all.
URL
http://app.ecwid.com/api/v1/STOREID/batch?key1=query1&key2=query2&...
Format
JSON
HTTP Method
GET
Example: http://app.ecwid.com/api/v1/STOREID/batch?cats=categories%3fparent%3dCATEGORYID&pros=products%3fcategory%3dCATEGORYID
will return a JSON map in the form {"cats" : [subcategories of the CATEGORYID], "pros": [products in the CATEGORYID]}.
Standard Response Codes
The Product API uses standard HTTP response codes to indicate success or error.
| 200 OK |
Success. |
404 Not Found
|
Store/category/product ID is not found.
|
400 Bad Request
|
Wrong URL parameters.
|
500 Internal Server Error
|
Something is wrong on our server. Submit a new bug report about this issue.
|
403 Forbidden
|
Ecwid account type does not allow this kind of requests. Consider upgrading your account.
|
FAQ
What's an API?
The acronym "API" stands for "Application Programming Interface". An API is just a defined way for a program to accomplish a task, usually retrieving or modifying data.
Does Product API require authentication or API key?
No. Since API returns only public information already visible for all your customers, no authorization is required.
What information is returned?
API returns information about all enabled products and categories in your store. Also it returns some general information about your store, like its name or currency.
Does Product API have some rate limits?
Yes. The default rate limit per IP for calls to the REST API is 100 requests per 5 seconds, 400 requests in 50 seconds, 1400 requests in 500 seconds.
No more than 10 simultaneous connects from one IP
Who can use this API?
This feature is available for paid Ecwid accounts only. Compare plans: www.ecwid.com/compare-plans.html
I want to create a module for Ecwid, but if I don't have a paid account. How can I test an API?
There are two possible solutions:
- You can use "1003" Store ID to test your module. It's our demo store and it has an API enabled.
- You can contact us and we will provide you with the access to a test API server.
Do you have any ready libraries?
Yes, we have a PHP library:
How do I report bugs and request features?
Please report all bugs to our bugtracker and all ideas to our ideas tracker.
How can I keep up with changes to the Ecwid API?
There are a number of ways to follow the changes we make to the Ecwid API:
