Ecwid Partner API

Latest revision May 21, 2021

Creating new Ecwid account

Example in Java

Changing the account subscription

Suspending/resuming a user account

Deleting a user account

Getting info about the store

Checking a user account status

How to clone a store using the Ecwid Clone Store API

Getting a list of all stores that are registered for the given partner

Getting the list of partner plans, available for subscription

Single sign-on (SSO) using Partner Key mechanism

Embedding Ecwid Control Panel

Implementing Custom Save Button

Static Embedding of Ecwid Widget

Dynamic Embedding of Ecwid Widget

Deferred Initialization of Ecwid Widget

Improving SEO with Static Pages

Centering popups in iframe (storefronts and stores’ control panel)

Tracking customer navigation in embedded control panel

Color Management for Ecwid Widget (Chameleon)

Accessing Ecwid Developer API

Creating stores using Developer API

Single Sign On to the control panel using the Developer API and store access tokens

SSO session invalidation

Product API extensions for partners

Setting language of control panel

Billing Rules

Trial plans in Ecwid

Define upgrade URLs

Profile-based Ecwid SSO

Definitions
Intro. What problem are we solving here?
Profile-based SSO API Basics
How to make it work for new users
Partner gets an Ecwid profile ID when creating first Ecwid store for the user
Partner specifies the profile ID when creating new Ecwid stores for the existing user
Partner passes the profile ID parameter in SSO request when logging in the user to an
Ecwid control panel
Example
How to make it work for the existing users
Partner finds Ecwid stores belonging to the user and their profile IDs
Partner assigns the same profile ID for all Ecwid stores belonging to the user
Note on security
Creating new Ecwid account
To create new Ecwid account just make a POST request to this URL:
https://my.ecwid.com/resellerapi/v1/register?register=y
with these parameters:
- email: store email, will be used as a login
- password
- name: Owner full name
- key: API key
- plan: internal name of the active partner plan to create the initial subscription for the store

- billing (optional): set billing period for the account subscription. Possible values: monthly,
annual. If parameter is not set then monthly value is used by default.
- is_trial (optional): enables trial period for the store. Possible values: false, true.
Type of value should be string (mandatory). Use this parameter to subscribe store to the trial
version of paid plan. Number of days in trial period is set individually for every partner’s plan. If
parameter is not set then false value is used by default. Ecwid will not bill partner for the
duration of free trial. After free trial expires partner will be billed according to selected plan rates.
If customer did not subscribe for the services partner must suspend/delete account at the end of
free trial period to avoid charges for this account.
- ip (optional): IP address of owner. It will be used to detect owner’s location and automatically
configuring store defaults (including time zone and default language) for that location. If you
don’t know IP but know the country of the owner, just specify any IP belonging to the country to
correctly pre-configure the store defaults.
- timezone (optional) Time zone of the store. (e.g. America/New_York, Europe/London,
Asia/Tokyo, Africa/Johannesburg see timezones in Ecwid backend for the full list).
- defaultlanguage (optional) Storefront default language. Two letter language code (e.g. en, fr,
exceptions: es_419, pt_BR)
- profile_id (optional) assign a new store to the existing profile ID in Ecwid (see Profile-based
Ecwid SSO for resellers for more details)
- returnProfileId (optional) if set to 'true' profile ID will be returned in response in addition to the
store ID. The profile ID format is a string starting with a 'p' and following with numbers. Example:
p987654321
- template (optional): a store template as an XML file attachment, containing settings, demo
products and demo orders of a new store. The default template is described here. The default is
applied on any store creation. You can change the new store settings and data by supplying
your own template XML. To do that, download the default template and read comments in the
XML document. You can either copy the entire template, or just any part you wish to change, as
long as the structure preserves. For example, the following template file will replace the default
<shippingAndTaxSettings>, effectively installing different zones:

<template><owner><storeConfiguration>
 <shippingAndTaxSettings>
<shippingSettings></shippingSettings>
<taxSettings></taxSettings>
<world id="WORLD">
<name>The World</name>
</world>
<zones id="1">
<countryCodes>US</countryCodes>
<countryCodes>UM</countryCodes>
<countryCodes>VI</countryCodes>
<name>USA</name>
</zones>
</shippingAndTaxSettings>
</storeConfiguration></owner></template>

- “Accept-Language” HTTP header can be used as usual to specify the store’s language. If
missing, English language is used.

Here is a more advanced example that configures PayPal Standard payment gateway by
default and disables the “Phone order” payment method.

It is possible to mark account for different purposes for example to distinguish test and
production accounts, or mark account as belonging to sub-partner. For this purpose it is
necessary to use the <source> element in XML template when creating a new account:
<owner>
<source>test_account</source>
..
</owner>
or
<owner>
<source>sub-partner name</source>
..
</owner>

Later you can access value of source parameter using API function status

If a new account/store is created successfully, Ecwid will return the 200 OK HTTP status and
this code:

<?xml version="1.0" encoding="UTF-8"?><ownerid>OWNERID</ownerid>

where OWNERID is an ID you should use in the widgets.

If Ecwid already has a store with the same email, the 409 status will be returned (in this case
please use the profile_id parameter to create a new store, please see detailed instructions).
If the e-mail isn't valid: 400
If API key isn't valid: 403

Example in Java
The following example demonstrates using a template attachment in Java programming
language. The following libraries are required to run the example:
Commons HttpClient 3.1, Commons Codec, Dom4j for parsing the response.

import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.methods.*;
import org.apache.commons.httpclient.methods.multipart.*;
import org.apache.commons.httpclient.params.*;
import org.dom4j.Document;
import org.dom4j.io.SAXReader;

/**
* Example Java code for creating a store using reseller API and a custom template defining
* one geographical zone.
*/
public class TestClient {
public static void main(String[] args) throws Exception {
HttpClient client = new HttpClient();
PostMethod post = new
PostMethod("https://my.ecwid.com/resellerapi/v1/register?register=y");
String xml =
"<template><owner><storeConfiguration>"+
"<shippingAndTaxSettings>"+
"<shippingSettings></shippingSettings>"+
"<taxSettings></taxSettings>"+
"<world id=\"WORLD\">"+
"<name>The World</name>"+
"</world>"+
"<zones id=\"1\">"+
"<countryCodes>US</countryCodes>"+
"<countryCodes>UM</countryCodes>"+
"<countryCodes>VI</countryCodes>"+
"<name>USA</name>"+
"</zones>"+
"</shippingAndTaxSettings>"+
"</storeConfiguration></owner></template>"
;
Part[] parts = {
new StringPart("email", "test@example.com"),
new StringPart("name", "Tester Tester"),
 new StringPart("password", "tester"),
new StringPart("key", "12345"),
new StringPart("plan", "ECWID_FREE"),
new FilePart("template", new ByteArrayPartSource("template.xml",
xml.getBytes("UTF-8")))
};
HttpMethodParams params = new HttpMethodParams();
post.setRequestEntity(new MultipartRequestEntity(parts, params));

if (client.executeMethod(post) != 200) {
System.err.println("Error creating store: " + post.getStatusLine());
return;
}

SAXReader reader = new SAXReader();

Document doc = reader.read(post.getResponseBodyAsStream());
int ownerid = Integer.parseInt(doc.getRootElement().getText());

System.out.println("Successfully created: "+ownerid);

}
}

Changing the account subscription

You can change the account subscription for the account previously created by you with the
help of /resellerapi/v1/register API call (see above). Changing the subscription will stop the
current subscription and create a new one for the plan provided.

To change the plan make a GET or POST request to this URL:

https://my.ecwid.com/resellerapi/v1/subscribe
with the following parameters:
● ownerid: the Ecwid store ID, as an integer number
● key: your reseller API key previously used to create the account
● plan: the internal name of the active partner plan to create the initial subscription for the
store
● billing (optional): set billing period for the account subscription. Possible values:
monthly, annual. If parameter is not set then monthly value is used by default.

To unsubscribe from the current plan to the default one make a GET or POST request to this
URL:
https://my.ecwid.com/resellerapi/v1/unsubscribe
with these parameters:
● ownerid: the Ecwid store ID, as an integer number
● key: your reseller API key previously used to create the account
This will stop your current subscription for the account and bring it back to the free plan, defined
for the partner. The same result can be achieved by calling /subscribe and specifying your
default plan name in the plan parameter.

If the request succeeds, the response 200 OK is returned, and the new expiration date is
provided in the following XML format:
<subscribe-response>
<expirationDate>2012-05-20T06:44:53.627-04:00</expirationDate>
</subscribe-response>

If the new subscription has no expiration date, the empty xml is returned:
<subscribe-response/>

If the request fails, the response will contain the reason for the failure, for example:
HTTP ERROR 400
Problem accessing /400. Reason:
Plan 'TEST' not found for partner TestPartner

Suspending/resuming a user account

You can suspend or resume a user account you have previously created with the
/resellerapi/v1/register API call (see above). Suspending a user account prevents the
storefront from showing any products or creating orders. Suspended accounts allow users to
use their Control Panel though.

To suspend, make GET HTTP request to the following URL:

https://my.ecwid.com/resellerapi/v1/suspend

To resume previously suspended account, use this URL:

https://my.ecwid.com/resellerapi/v1/resume

The parameters for both calls are the following:

● ownerid - the Ecwid store ID, as an integer number
● key - your reseller API key which was used to create the account

On success, both calls return HTTP status 200. Suspending an already suspended account and
resuming an already active account makes no effect and returns status code 200.
Deleting a user account
If you want to delete an account, you should make GET or POST HTTP request to the following
URL:

https://my.ecwid.com/resellerapi/v1/delete

The parameters for this call are the following:

● ownerid - the Ecwid store ID you want to delete
● key - your reseller API key

On success, you will see HTTP status 200. If you cannot delete an account (e.g. it wasn't
created by you), the 403 HTTP error will be returned.

Important notice: deleting account does not remove its billing records. At the end of the billing
cycle you will be invoiced for the period that account was active.

Getting info about the store

If you want to get info about one of partner’s stores you should make GET HTTP request to the
following URL:
https://my.ecwid.com/resellerapi/v1/stores

The parameters for this call are the following:

● ownerid - the Ecwid store ID information you want to get
● key - your reseller API key

On success, it will return HTTP status 200 and an XML document listing apps installed,
information about the store subscription and billing, plan features enabled/disabled, shipping
and payment configuration, tax settings and zones.

Checking a user account status

You can query status information on an account created previously by the
/resellerapi/v1/register API call (see above). Make a GET or POST HTTP request to the
following URL:

https://my.ecwid.com/resellerapi/v1/status
The parameters are:
● ownerid - the Ecwid store ID, as an integer number
● key - your reseller API key which was used to create the account

On success, the call returns HTTP status 200 and the XML document with the following tags:
● ownerid - echoes the ownerid in the request
● profile_id - Ecwid profile ID associated with this store
● suspended - “true” if the store was suspended
● closed - “true” is the store was closed by the user
● email - the current email of the account
● name - the person name in the account profile
● traffic - amount of web traffic consumed by the store since the start of the month
● storage - amount of billable storage occupied by the store, including store images and
files.
● shippingAndTaxSettings - current zones, shipping and tax settings
● account-type - information about the subscription. The most useful tag there is
subscription/originalProduct, which contains the current user’s plan.
● carrier-settings - (deprecated)
● paymentmethods - payment method list
● total - total of all orders in the store currency, except unfinished orders.
● currency - store currency ISO code
● productCount - product count
● categoryCount - category count
● source - value of source parameter that was defined during account creation. If not
defined the tag is missing

If the store with such ID does not exist, the call returns HTTP status 404.
If the store does not belong to your API key, the call returns HTTP status 403.

How to clone a store using the Ecwid Clone Store API

The Ecwid Partner APIs allows an Ecwid reseller to create and manage accounts (stores) in
Ecwid. In some cases, it may be convenient to have a single "template" store and clone it to
create new stores — to make it easier pre-filling new stores with products, settings etc. The
Ecwid Clone Store API can be used to do that.

Please refer to this documentation for details:

https://docs.google.com/document/d/1aSNdOEXqDs3BQdPWHnqYLgUb_d0SNC9lYMKQ5LibP
c4/edit?usp=sharing
Getting a list of all stores that are registered for the
given partner
To retrieve a list of your customers’ stores, make GET or POST request to the following
endpoint URL: https://app.ecwid.com/resellerapi/v1/stores

Include the following parameters:

● date.from Stores created after the given date/time will be returned. The date/time is
given either as a UNIX timestamp or a ‘YYYY-MM-DD’ string.
● store.id (optional). If specified, select a store with the given ID
● url.substring (optional). If specified, limits stores only to those having certain substring
in their URL.
● email.substring (optional) If specified, limits stores only to those having certain
substring in their email.
● date.to (optional). If specified, limits stores to those created before the given date/time.
The date/time is given either as a UNIX timestamp or a ‘YYYY-MM-DD’ string.
● timezone (optional, default is ‘GMT’). The name if the timezone used to parse date.from
and date.to fields.
● suspended (optional). If specified, lists only stores with the given “suspended” status.
Possible values are: “y”, “yes”, “1”, “true”, “t”, “n”, “no”, “0”, “false”, “f”.
● order (optional, defaults to “id"). Specifies criteria used to sort stores. One of “id”,
“email”, “url”, “traffic”, “storage”, ”date”, “id_desc”, “email_desc”, “url_desc”,
“traffic_desc”, “storage_desc”, ”date_desc”.
● key. Your partner API key.
● offset (optional, default is "0"). Starting offset of the result window. Used to create
pagination.
● limit (options, defaults to “20"). Number of stores to return, an integer value in the range
[0; 100].

On success, returns store list in the following format:

1 <storeList>
2 <stores>
3 <id>STORE ID</id>
4 <channelId>PARTNER ID</channelId>
5 <name>Store name</name>
6 <nick>Store owner's nickname</nick>
7 <email>Store owner's email</email>
8 <url>Store URL</url>
 9 <planName>Name of partner plan</planName>
10 <planChangeableByReseller>either 'true' or 'false'</planChangeablebyReseller>
11 <planExpiration>Plan expiration date</planExpiration>
12 <suspended>'Suspended' status, either 'true' or 'false'</suspended>
13 <test>’true’ for test accounts and ‘false’ for others</test>
14 <trial>’true’ for trial subscriptions and ‘false’ for life</test>
15 <traffic>Traffic consumed since start of the month, bytes</traffic>
16 <storage>Storage consumed by the store data, bytes</storage>
17 <registered>Store registration date</registered>
</stores>
...more store data...

<total>TOTAL NUMBER OF STORES MATCHING CRITERIA</total>

</storeList>

On error, returns one of the following HTTP status:

● 403 - wrong API key
● 412 - wrong parameter format
● 500 - internal error

Getting the list of partner plans, available for

subscription
You can get the list of active partner plans, available for subscription. To get them make a GET
request to this URL:
https://my.ecwid.com/resellerapi/v1/plans?key=<your reseller API key>
If the request succeeds, the response code 200 is returned, and the response body will contain
the list of plans in XML format:
<planList>
<plans>
<active>true</active>
<canUserCancel>true</canUserCancel>
<channelId>TestPartner</channelId>
<ecwidBilling>true</ecwidBilling>
<id>3</id>
<maxCategoryCount>1500</maxCategoryCount>
<maxProductCount>30000</maxProductCount>
<monthlyPrice>17.0</monthlyPrice>
<name>TEST_PLAN_NAME</name>
<premiumFeatures>true</premiumFeatures>

<sendCancellationEmailToBillingManager>true</sendCancellationEmailToBillingMa
nager>
<suspendWhenExpired>false</suspendWhenExpired>
 <title>Test Plan Title</title>
<trialDays>14</trialDays>
</plans>
...
</planList>
If the request fails, the reason for the failure is returned.

Single sign-on (SSO) using Partner Key mechanism

Please note that Single Sign On to control panel using the Developer API is now available and
have more functionality. We recommend to switch to the Developer API SSO.

In order to login a user into Ecwid store control panel, the control panel should be opened
through the following URL:

https://my.ecwid.com/cp/partner-login?ownerid=[ID]&t=[TIMESTAMP]&login_sha1token=[TOK
EN]&place=[PAGE_HASH]&logout_url=[LOGOUT_URL]&upgrade_url=[UPGRADE_URL]&lang=[LANGUAG
E_CODE]&inline&profile_id=[PROFILE_ID]

For private label partners my.ecwid.com may be substituted with the domain where partner’s control panel
is located.

where
● [ID] - Store ID, e.g. 1003
● [PROFILE_ID] (optional) - log in to specified profile id (see Profile-based Ecwid SSO for resellers
for more details)
● [TIMESTAMP] - unix timestamp of a token creation time. Time should be in UTC and
timestamp should be in seconds.
● [TOKEN] - the token itself that is a SHA1 hash of concatenation of the following
parameters: timestamp + store_id + channel_id + partner_api_key
Please generate the token in lowercase (mandatory!)
● [PAGE_HASH] - (optional) the hash part of control panel page’s URL-address that
should be opened after sign-on (Dashboard page if was not defined)
● [LOGOUT_URL] - Ecwid will redirect a user to this URL if his/her session is expired.
Usually it is URL of a partner’s control panel or “log in” page.
● [UPGRADE_URL] - allows setting an upgrade URL for every partner’s store. Ecwid will
redirect a user to this URL if he/she clicks any upgrade button within store Control panel
(e.g. http://take.ms/l7qnX ). For more information on upgrade URLs format refer to
Define upgrade URLs
● [LANGUAGE_CODE] - a two letter language code for the store control panel
● [inline] - (optional) displays control panel in iframe friendly manner with header and
footer removed
 The UPGRADE_URL parameter works in the following way:
- When passing a value via UPGRADE_URL - that value is assigned as Upgrade
URL for that particular store.

- When passing empty value via UPGRADE_URL - a current Upgrade URL for that
store is reset. In this case, one of two options is possible:
a) If Channel_Upgrade_URL (URL that is set for a partner on the Ecwid side) is set,
Ecwid will redirect a user to that Channel_Upgrade_URL.
b) If Channel_Upgrade_URL is not set, a user will not be redirected anywhere and
just see a popup with an explanatory text, e.g. http://take.ms/2ymqu .

- If UPGRADE_URL is not passed at all - a current Upgrade URL (that was set
earlier) is used.

● [send_postmessage_on_upgrade_button_click] (optional) - Enables sending

postmessage when upgrading. Possible values: false, true.

Ecwid Control Panel is often embedded in a partner service in a form of an iframe. In this
case, when a merchant clicks upgrade button, Ecwid can send a postmessage to the
"parent" window and then the partner admin interface handles it accordingly. For
example, the partner can show a popup where the merchant chooses a plan and then is
directed to finish the upgrading process http://take.ms/aZrjQ.

Please note that when both

upgrade_url
and send_postmessage_on_upgrade_button_click
parameters are passed in the SSO URL simultaneously then postmessages only will be
sent.

When clicking Upgrade buttons, Ecwid sends postmessage in the following format:
{ event: 'upgrade-link-click', feature: 'coupons', plan: 'PARTNER_PLAN_NAME' },
where
feature: name of a feature an upgrade button was clicked for;
plan: name of a plan where the feature is available.

Please note that the option to send upgrade postmessage can be enabled on the partner
channelID level, in this case, postmessages will be sent for all stores of the partner.
If you need this option please let the Ecwid Bizdev team know.

Please note:
- A token is valid for 5 minutes from the time specified in the timestamp
- The URL provided works with HTTPS only, not HTTP
- It is possible to autologin users only into the stores that were created by partner via Partner
API
- SSO session will expire in 27 hours after the last active RPC request from the control panel.
So if the control panel is open in your browser it will keep sending heartbeats and the session
will not expire.

PHP code sample:

<?php
$time = time();
$store_id = STORE-ID;
$channel_id = "YOUR-CHANNEL-ID";
$apikey = "YOUR-API-KEY";
$token = $time . $store_id . $channel_id . $apikey;
$token = sha1($token);

echo
"https://my.ecwid.com/cp/partner-login?ownerid=$store_id&t=$time&login_sha1token=$token&place=
order&logout_url=http://example.com&upgrade_url=http://billing.com" . "\n";
?>

Embedding Ecwid Control Panel

For seamless customer experience it is possible to embed Ecwid control panel into a third party
product using seamless iframe. Please make sure that you are using the Ecwid SSO for
seamless customer experience. The iframe will automatically adjust its height depending on the
content of control panel page. Below is an example of simple HTML page with embedded Ecwid
control panel:

<html>
<head>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
</head>

<body>

<h1>Sample of Ecwid control panel embedding</h1>

<script type='text/javascript'>//<![CDATA[
window.onload=function(){
// Create IE + others compatible event handler
var eventMethod = window.addEventListener ? "addEventListener" : "attachEvent";
 var eventer = window[eventMethod];
var messageEvent = eventMethod == "attachEvent" ? "onmessage" : "message";

// Listen to message from child window

eventer(messageEvent,function(e) {
$('#ecwid-frame').css('height', e.data.height + 'px');
},false);

$(document).ready(function(){
$('#ecwid-frame').css('height', '700px');

$('#ecwid-frame').attr('src', 'https://my.ecwid.com/cp/CP.html?inline');
});

}//]]>

</script>

<div id="wrap">
<iframe seamless id="ecwid-frame" frameborder="0" width="100%" height="700"
scrolling="no"></iframe>
</div>

</body>
</html>

Implementing Custom Save Button

You can natively implement buttons in your product to save changes in the Ecwid control panel.
This is useful if you display an Ecwid control panel in a webview of a mobile app or want to have
your original controls to save changes.
Please note that Save page functions described below won’t work when the control panel is
embedded in an iframe.

To hide Ecwid save button use parameter: hide_save_button=true when embedding control
panel e.g. https://my.ecwid.com/cp/CP.html?inline&hide_save_button=true
To control saving data in Ecwid control panel please use the following Javascript API functions:

EcwidControlPanel.onSavePageDataRequired(callback) - Ecwid will fire this callback when it

detects that data was changed and requires saving.
EcwidControlPanel.savePageData() - save unsaved data in Ecwid control panel.
EcwidControlPanel.onSavePageData(callback) - callback is fired when data is saved.
EcwidControlPanel.revertUnsavedPageData() - discard unsaved data in Ecwid control panel.
EcwidControlPanel.onRevertUnsavedPageData(callback) - callback is fired when data is
discarded.

Note: when customer leaves Ecwid control panel with unsaved changes it will display popup
with warning to save changes even if save button is hidden.

Static Embedding of Ecwid Widget

In some cases it is necessary to load Ecwid widgets simultaneously with loading of a web page.
This way of loading is called Static loading. For example, sitebuilders can load Ecwid widgets
statically when customers publish their websites (with a store) live.

Please refer to the following articles to find more information regarding the Ecwid widgets
including embed codes:

Minicart / Bag - displays items quantity in the shopping bag.

Horizontal Categories - displays product categories in the horizontal list with tabs

Vertical Categories - vertical list of categories

Search Box - allows to search your products

[IMPORTANT]:
- Use a correct domain in the script.js
In the articles below the ecwid.com is used in the script.js (https://app.ecwid.com/script.js?...)
Please note that this correct for partners who use ecwid.com as the domain for their store
Control panel.
If another domain is set as the domain for partner stores Control panel, in this case a partner
should use that custom domain in the script.js.

Please contact with Ecwid Bizdev team and clarify your domain for the store CP and other
questions regarding the script.js if any.

- Call the script.js only once!

Please note that the script.js (https://app.ecwid.com/script.js) should be called only once before
loading of the widgets or simultaneously with loading of the first widget (but only once!).

Please review Ecwid demo store as an example of static embedding of the widgets:
https://mdemo.ecwid.com/
Dynamic Embedding of Ecwid Widget

In some cases it is necessary to dynamically create and destroy Ecwid widget within HTML
page. This is useful for dynamic sitebuilders that switch to online store page without actually
reloading page (e.g. making it visible). You should use window.ecwid_dynamic_widgets variable to
enable dynamic widget creating in Ecwid. See the example below that shows how to create and
destroy Ecwid widget through javascript functions.

Please note that this method allows to embed the Product browser widget only. If you need to
embed other widgets dynamically, please, use the code for deferred widget initialization (next
point).

Please note that this method is slower than direct embedding of Ecwid widget so you should
use it only if you need dynamic widget creation.

<div id="my-store-1003"></div>
<script>
window.ecwid_script_defer = true;
window.ecwid_dynamic_widgets = true;

if (typeof Ecwid != 'undefined') Ecwid.destroy();

window._xnext_initialization_scripts = [{
widgetType: 'ProductBrowser',
id: 'my-store-1003',
arg: ["categoriesPerRow=3","views=grid(3,3) list(10)
table(20)","categoryView=grid","searchView=list"]
}];

if (!document.getElementById('ecwid-script')) {
var script = document.createElement('script');
script.charset = 'utf-8';
script.type = 'text/javascript';
script.src = 'https://app.ecwid.com/script.js?1003';
script.id = 'ecwid-script'
document.body.appendChild(script);
} else {
ecwid_onBodyDone();
}

</script>
Deferred Initialization of Ecwid Widget

Sometime it is necessary to delay widget initialization while host page finish initialization
procedures. This is useful when host site is built dynamically using libraries such as React js.

Use this integration code for deferred widget initialization:

<div id="my-store-1003"></div>
<div id="productBrowser"></div>
<script>
window.ecwid_script_defer = true;
var script = document.createElement('script');
script.charset = 'utf-8';
script.type = 'text/javascript';
script.src = 'https://app.ecwid.com/script.js?1003';
document.getElementById('my-store-1003').appendChild(script);
window._xnext_initialization_scripts = [
{ widgetType: 'ProductBrowser', id: 'productBrowser', arg: [
'"categoriesPerRow=3","views=grid(4,4) list(10)
table(20)","categoryView=grid","searchView=list","style=","responsive=yes","id=productBrowser"'
]}
];</script>

Improving SEO with Static Pages

Ecwid widgets are indexed by Google. However Google is indexing HTML pages faster and
deeper than dynamic Javascript widgets. So as a measure to improve indexing you can use
Static Store Pages API https://api-docs.ecwid.com/reference/static-store-pages to add
indexable HTML content to your store.

This method will work only if your page with Ecwid widget is generated dynamically with a server
side script e.g. Python, PHP, ASP etc. You need to add a piece of code to your page that
fetches the HTML version of a store page and insert it into your page. Static Store Pages API
also returns Meta tags and Open Graph tags it is highly recommended to insert them into your
page as well.
You should do it dynamically each time the store page is loaded in the customer’s browser.
Google bot will continue following links in the static page and will index the entire product
catalog.
Store customers will be interacting with the dynamic Ecwid widget. To prevent customers from
seeing a static copy of the store page you need to add a Javascript code that will hide the static
part.

You can use the code example provided below for hiding static content:

#html_selector - is a HTML selector of the static content.

<script data-cfasync="false" data-no-optimize="1" type="text/javascript">

function createClass(name,rules) {

var style = document.createElement('style');

style.type = 'text/css';

document.getElementsByTagName('head')[0].appendChild(style);

if(!(style.sheet||{}).insertRule)

(style.styleSheet || style.sheet).addRule(name, rules);

else

style.sheet.insertRule(name+'{'+rules+'}',0);

createClass('#html_selector', 'display:none;');

</script>

<div id=’#html_selector’>
 Static HTML code here

</div>

Sample code in PHP for extracting productid and categoryid from SEO friendly URL
<?
$pattern = '!.*-(p|c)([0-9]+)(\/.*|\?.*)?$!';
if( preg_match( $pattern, $current_url, $matches ) ) {
return array();
}
$modes = array(
'p' => 'product',
'c' => 'category'
);
return array( 'mode' => $modes[$matches[1]], 'id' => $matches[2] );
?>
Returned values:
mode = product - this is a product page
mode = category - this is a category page
mode is empty - this is a home page
id - productid or categoryid. Use it when calling the Static Pages API.

We recommend to cache static content on your side to provide better site performance. You
should use the Store Changes Stats API endpoint to determine when the cache becomes
obsolete. productsUpdated and categoriesUpdated fields provide an indication when it is
necessary to refresh cache.

Centering popups in iframe (storefronts and stores’

control panel)
Ecwid can be embedded to a website in many ways. Sometimes a storefront can be inserted in an iframe
container due to the limitations of a platform. To make sure that all popup windows such as customer
account login popup are displayed in the center of an iframe, use the example code below in a main
frame of your page. The example can be used for the storefront and the stores’ control panel.

Example of centering popups:

<script src='https://d1e443hvef5jf2.cloudfront.net/static/iframeintegration.js'></script>
<script type='text/javascript'>

window.addEventListener('load', function(e) {
setupEcwidPopupCentering('#myframe');
});

</script>

setupEcwidPopupCentering() function accepts one argument, which is the ID of an iframe element, where
Ecwid storefront is loaded. In order to work, setupEcwidPopupCentering() function needs to have
iframeintegration.js file loaded for that frame.

Tracking customer navigation in embedded control

panel
Each time customer opens new page in embedded Ecwid control panel it sends following postmessage to
the parent window:

{
'action': 'pageLoad',
'data': {
'page': {
'title': 'Catalog',
'path': 'products',
}
},
'height': 1200
}

This functionality is useful when creating deep product integration with Ecwid. For example change
content of parent window depending on the page opened in Ecwid control panel.

Color Management for Ecwid Widget (Chameleon)

When embedding Ecwid widget into a website there is an easy way to make sure that Ecwid colors
matching site colors. There are two options to define colors for Ecwid stores: automatic and manual.

- Automatic color detection

You should add the following data structure before Ecwid widget integration:
<div><script type="text/javascript">
window.ec = {
config: {
chameleon: {
colors: 'auto'
}
}
}

Ecwid will change its main colors depending on website colors and will automatically calculate all
intermediate colors in the interface to make sure that all elements are legible and have good contrast.

Please note that for some website themes the automatic mechanism may detect colors not ideally.
We recommend checking how colors were detected.

Please note that if Ecwid widgets are embedded into an iframe, the automatic mechanism will not work. In
this case additional actions are required, please get in touch with Ecwid Bizdev team for more information
on this.

In cases when the automatic mechanism cannot be used, please use the manual mechanism:

- Manual color defining

Allows to define colors for Ecwid stores manually. Example of data structure that should be added before
Ecwid widget integration:

<div><script type="text/javascript">
window.ec ={
config:{
chameleon:{
'color-link': '#ffffff' ,
'color-button': '#00ff00',
'color-foreground': '#a1d3de' ,
//Set widget background transparency through alpha channel
'color-background': 'rgba(29,29,29,0)' ,
'color-price': '#df0739'
}
}
}

Turn off automatic background color in gallery

When the automatic Ecwid background color in the gallery does not work well, please use the parameter
below to switch off automatic background color and use the color set manually.
ec.config.chameleon.colors.gallery.use_exact_colors = true
Accessing Ecwid Developer API

Ecwid provides Developer API http://api.ecwid.com/ that can access and manipulate data in
Ecwid stores.

If certain permissions are granted partner can access Developer API on behalf of customers.
This is useful for building various types of integrations with third party products, consolidating
customer data, building reports etc.

To access Developer API for a store it is necessary to retrieve access token that is unique for
every store. Normally receiving access token requires manual permissions granting by customer
as described here http://api.ecwid.com/#get-access-token, however for Ecwid partners there is
an alternative flow that allows generating access token without explicit confirmation from
customer.

Before accessing the Developer API, you must ensure that this functionally is set and enabled
for your partner account. You will need the following access credentials that should be provided
to you by Ecwid: client_id and client_secret. If you do not have this data please get in touch
with Ecwid representative.

Receiving access token (alternative flow for partners)

To receive token for online store make POST request to the following endpoint:
https://my.ecwid.com/api/oauth/token/{ownerid} and send the following parameters:

client_id required Application ID

client_secret required Application secret key

grant_type required Must be

authorization_code

{ownerid} in the endpoint path should be replaced with the Store ID number.
Please make sure that the correct domain my.ecwid.com is used to make POST request!
Ecwid responds with a JSON-formatted data containing the access token and additional
information. Please refer to http://api.ecwid.com/#get-access-token STEP 3 to get information
about format of response.

Important: an access token does not expire. So you will need to retrieve the token only once per
store and then use it as many times as you need. In other words, you should save the token in
your system and use it for all API calls instead of generating it every time you access the store
over API.

After receiving access token partner should use it to access Developer API as described in the
documentation http://api.ecwid.com

Creating stores using Developer API

To create new store special Developer API endpoint should be used:

POST:
https://app.ecwid.com/api/v3/stores?appClientId={appClientId}&appSecretKey={appSecretKey}
&returnApiToken={true/false}

Parameters:
There are 2 mandatory parameters that you need to specify during account creation.
email string Store owner’s email
name string Store owner’s name

Set returnApiToken to true to include token into API response. When store is successfully
created, API will return StoreID (id) of newly created store and API token that should be saved
and used later for API calls for this store.

If you do not yet have appClientId and appSecretKey please contact Ecwid representative at
partneraccount@ecwid.com and we will provide you with necessary credentials.

When creating new store you can send multiple optional parameters to pre-configure the store.
Please refer to this documentation for details:
https://lamps.ecwid.com/~rick/web/apiDocs/api_docs.htm#stores

If you need to check if there is a store registered with the specified email, please use the
following GET request:
GET:
https://app.ecwid.com/api/v3/stores?appClientId={appClientId}&appSecretKey={appSecretKey}
&email={email}
If 404 error returns that means that store with given email is not found, so you can create a
store with that email.

Please refer to this documentation for details:

https://lamps.ecwid.com/~rick/web/apiDocs/api_docs.htm#check-if-store-exists

Single Sign On to the control panel using the

Developer API and store access tokens

Use the following endpoint to display Ecwid control panel and automatically log in customer into
it:
my.{domain}/api/v3/{ownerId}/sso?token={token}&timestamp={timestamp}&signature={signature
}

Parameters:
● domain - if your instance of Ecwid is located on custom domain please insert it here.
Otherwise domain should be ecwid.com
● ownerId - unique numeric identifier of the store. Also known as StoreID
● token - ApiToken that was generated during store creation. Also could be received via
oAuth endpoint or via Partner API
● timestamp - UNIX timestamp for current date and time e.g. 1492688357
● signature - is sha256 hash from concatenation of ownerid, token, timestamp and
app_secret without spaces between them:
sha256(ownerid+token+timestamp+app_secret). Signature should be generated without
sha256 secret key. Please generate the signature in lowercase (mandatory!)
● place, inline, logout_url, upgrade_url,
send_postmessage_on_upgrade_button_click - see parameter description in Single
sign-on (SSO) using token mechanism
● hide_visit_storefront_menu=true - (optional) hides the Visit storefront link
http://take.ms/ztmFq
● hide_help_menu=true - (optional) hides the Help menu http://take.ms/lhoJD . The Help
menu is usually hidden for White-label partners.
● hide_profile_menu=true - (optional) hides the Profile menu (round icon with pop-up
menu) http://take.ms/PuAbJ
● hide_profile_header=true - (optional) hides all three elements: Visit storefront, Help
menu, Profile menu.
● hide_page_header=true - (optional) hides pages’ headers (text).
● hide_footer=true - (optional) hides the footer.
 ● hide_back_button=true - (optional) hides the Back button.
● hide_dashboard_background_image=true - (optional) hides the background image in
the new dashboard and replaces it with grey background. See screenshots:
The new dashboard in default mode - https://d.pr/free/i/VyBe8e.
The new dashboard with hidden background image - https://d.pr/free/i/yPwsNl.
● hide_staff_accounts_header_menu=true - (optional) hides “My stores” link in the
dashboard header https://d.pr/free/i/NmE3o7. “My stores” link allows opening admin
panel of stores where a user is logged in when using the Staff accounts feature.
● hide_vertical_navigation_menu - (optional) - hides main product navigation menu.
This is useful when partner wants to implement navigation menu in host application
outside iframe. Possible values: false, true. Ecwid will send post message
navigationMenuUpdated after initial load of control panel and each time when menu is
changed. Host application where Ecwid is embedded should listen for this message and
use its data to build menu.
● session_tag - (optional) arbitrary string that identifies a session. Used for SSO session
invalidation (logging out customer).

{
'action': 'navigationMenuUpdated',
'data': {
navigationMenuItems: [
{
'title': 'Catalog',
'path': 'products',
'items': {
{
'title': 'Products',
'path': 'products'
},
{
'title': 'Categories',
'path': 'category:id=0&mode=edit'
},
{
'title': 'Product Types',
'path': 'product-classes'
}
}
},

{
'title': 'Sales',
'path': 'orders'
...
},

...
]
}
'height': 1200
}
If you need to use external menu outside the iframe you can use the following code to open
necessary page in iframe without reloading it:

window.ecwidOpenAdminPage = function (place) {

jQuery('#ecwid-frame')[0].contentWindow.postMessage(JSON.stringify({
ecwidAppNs: "your-app-namespace",
method: "openPage",
data: place
}), "*")
}

You can populate "place" variable with necessary target e.g. orders, products, etc

If authorization is successful then customer will be redirected to control panel otherwise 403
error will be returned.

SSO session invalidation

Use this call to invalidate the SSO session (log out customer).
When you log in a user via APIv3 SSO, make sure that you are sending an optional session_tag
string parameter.
When you need to log out a user, please do POST request to
https://app.ecwid.com/api/v3/{storeId}/sso-logout?token=<YOUR-TOKEN> .
Use this JSON as its body:

{
"sessionTag": "SESSION-TAG-VALUE"
}

Product API extensions for partners

Extensions list:
● Managing list of enabled payment processors
● Managing storeURL
Setting values in the store profile
As a partner, you can set additional parameters using Product API that are not available to
regular users.
To modify store profile you should use PUT HTTP request to the following endpoint URL:
http://app.ecwid.com/api/v1/<ownerId>/profile?secure_auth_key=<Your partner API key>

In the body of request you should add JSON document, which may contain the following fields:
● enabledOnlineProcessors - enabled online payment processors for given ownerId.
Possible values are:
○ [] - allow all processors;
○ [“NONE”] - forbid all online payment processors;
○ [“processor1”, “processor2”, “processor3”] - allow all offline payment processors
and all listed online payment processors.
It is possible to turn on payment processors, that will be supported in future. For
example, you can enable “amex” for all your clients in advance and as soon as it will be
released, this payment will appear in all stores automatically.
● storeUrl - set store URL. Possible values are:
○ null - do not change store URL;
○ “” - reset store URL value;
○ new value of store URL. Must be valid URL beginning with “http://” or “https://”.
Response:
If storeUrl is not valid URL or does not start with “http://” or “https://”, server will respond with
error 400 Bad Request.
If JSON with fields enableOnlineProcessors or storeUrl sent with customer API key, server will
respond with error 403 Forbidden.

Examples of JSON document:

{
"enabledOnlineProcessors": [ "new1", "new2"],
“storeUrl”: “http://storename.com”
}
- enables all offline payment processors, online processors “new1” and “new2”, when they will
be added to Ecwid and sets store URL to “http://storename.com”.

Getting values through Product API

You can also get information about extended fields of store profile us API. To do so make GET
HTTP request to the following endpoint URL:
http://app.ecwid.com/api/v1/<ownerId>/profile?secure_auth_key=<Your partner API key>

Among all default fields, additional field enabledOnlineProcessors will be listed. Possible
values are:
 ● [] - allow all processors;
● [“NONE”] - forbid all online payment processors;
● [“processor1”, “processor2”, “processor3”] - allow all offline payment processors and all
listed online payment processors.

Upon requesting Product API with customer API key or anonymously, field
enabledOnlineProcessors will not be listed.

Setting language of control panel

By default Control panel will automatically switch to the correct language depending on
customer language setting in the web browser. However you can override this behaviour and
display control panel in certain language. Use lang parameter to when when accessing control
panel:

e.g. https://my.ecwid.com/cp/?lang=es

Use two letter language code to select necessary language:

Russian: ru
French: fr
German: de
Italian: it
Dutch: nl
Spanish: es
Brazilian Portuguese: pt_BR
Indonesian: id
Czech: cs
Hungarian: hu
Turkish: tr
Bulgarian: bg
Norwegian: no
Swedish: sv
Danish: da
Polish: pl
Finnish: fi

Please contact partneraccount@ecwid.com for more details.

Billing Rules
To better understand Ecwid will bill you for the services, please refer to this document.

Trial plans in Ecwid

Ecwid allows to create new stores subscribed to the trial version for the paid plan, if this
functionality was enabled during partner creation. It is possible to define number of trial days for
paid plan and the plan itself for which trial subscription will be available.
Note: Number of trial days and the trial subscription availability are defined by Ecwid and can’t
be managed through Partner API.

How to subscribe to trial plan?

Subscription to trial plan can be done together with new account creation only. (See: Create new
Ecwid account) There is no way to subscribe existing store to trial version of paid plan.
Among with general parameters required for the new account creation you will need to pass the
following:
- is_trial = true This parameter will mark the account as a “trial”
- plan = <name of the plan> Name of the plan for trial subscription (Usually discussed in
contract and can’t be changed afterwards).

What is next?
When the request on new trial account creation is received, Ecwid creates new account and
subscribes it to the paid plan with the expiration date calculated as:
date of subscription + number of trial days

Our internal script will check all trial subscriptions periodically and switch them to “Live” mode
automatically, when trial period is over. All trial subscriptions are converted to Live paid
subscription automatically and you will be billed for them accordingly.
 Define upgrade URLs

There are lot of upgrade URLs in Ecwid interface they trigger upgrades when customer want to
use certain functionality that is not available for the current plan. Normally they just lead to
Ecwid plans page but partner can redefine them and point to alternative location e.g. to
partner’s billing page where customer can manage their subscription.
This URL can be setup globally for all stores during initial deployment just specify it in partner
questionnaire. However if you have few sub resellers with individual billing systems that you can
define Upgrade URL on per store basis specifying URL in template XML for the store. Below is
an example of defining URL in template XML:

<owner>
<source>test_account</source>
<customUpgradeUrl>http://www.example.com?plan={plan}&storeid={ownerid}&AnyOtherPa
rameters</customUpgradeUrl>
...
</owner>

URL will be populated with following parameters:

{plan} - numinum available plan where requested feature is available
{ownerid} - Store ID of store that requested and upgrade
URL defined in template XML has higher priority over URL set up in global partner settings
You can also define Upgrade URL as parameter when doing SSO.

Profile-based Ecwid SSO

Definitions
Partner — Ecwid's reseller partner who provides their customers with Ecwid stores.
User — Partner's customer (seller)
Ecwid store — an Ecwid store with unique 'store ID' property.
Ecwid control panel — a web page allowing the user to manage a particular Ecwid store.
Ecwid profile ID — a special unique property that identifies the owner of an Ecwid store. Each
profile ID can be assigned to several stores meaning this person can open different Ecwid
control panels under the same login session.
Intro. What problem are we solving here?
Ecwid Control Panel can be embedded into the partner product seamlessly. Some partners
allow users to create several Ecwid stores under one partner account. For example, a user can
have several sites created under their account on the partner side and they need a separate
store added to each site. In this case, the partner may want to allow opening different Ecwid
control panels in different browser tabs — e.g. to allow the user to manage each site and store
in a separate tab.
Normally, Ecwid doesn't allow users to be logged in different accounts in the same browser —
each new login will override the previous ones so that all opened control panels will display the
same Ecwid account.
The doc below explains how to have several different Ecwid accounts opened in the same
browser.

Profile-based SSO API Basics

The solution relies on a special internal property of Ecwid accounts — 'profile ID'. Several
Ecwid stores can be assigned to the same profile ID, which tells Ecwid those actually belong to
the same person and can be opened in the same browser session with no need to log out and
log in again.
Ecwid automatically generates and stores that profile ID when a new store is created. However,
it's possible to specify the profile ID for a newly created store so that it's assigned to an existing
profile ID.
When using the Ecwid SSO API, it's possible to pass the profile ID parameter to let Ecwid know
the control panel is being opened under specific profile ID. If other stores under the same profile
ID are opened in the same browser, they won't be logged out — everything will work well.

Below are the details on how to do that for new and existing customers.

How to make it work for new users

Partner gets an Ecwid profile ID when creating first Ecwid store for the user
When the partner creates the first Ecwid store for the user via the Ecwid Partner API (the
`/resellerapi/v1/register` endpoint), the partner should pass a special parameter
'returnProfileId=true' to the request to make Ecwid return the generated profile ID of that store.
When the store is created, the corresponding profile ID will be returned in response in addition
to the store ID. The profile ID format is a string starting with a 'p' and following with numbers.
Example: p987654321.
The partner should store that profile ID corresponding to the user on their side.

Request:
POST
https://my.ecwid.com/resellerapi/v1/register?register=y&returnProfileId=true

Response:
<?xml version="1.0" encoding="UTF-8"?>
<store>
<ownerid>12345</ownerid>
<profileid>p987654321</profileid>
</store>

Partner specifies the profile ID when creating new Ecwid stores for the existing
user
If the same user requests to create another Ecwid store (e.g. to add a store to their another
site), the partner should pass the existing profile ID in the request query to the Ecwid Partner
API. This will assign a new store to the same profile ID in Ecwid.

Request:
POST https://my.ecwid.com/resellerapi/v1/register?register=y&profile_id=p98765

Partner passes the profile ID parameter in SSO request when logging in the user
to an Ecwid control panel
When opening the Ecwid control panel using the Ecwid SSO API, partner should pass the
profile_id query parameter to make Ecwid log that user into the specific profile ID.

Request:
GET https://my.ecwid.com/cp/partner-login?ownerid=[ID]&profile_id=p98765

That's it. Several logins to Ecwid control panel with the same profile ID can work in the same
browser without interrupting each other.
Example
Let's say a customer creates several sites in the partner product (e.g. sitebuilder) and adds a
new store to each site.
1) john@partner-sitebuilder.com requests to add a store to their site A
- The partner checks if the user already has an Ecwid profile ID assigned. This is a new
customer, so let's say there is no Ecwid profile ID on file.
- The partner uses the Ecwid Partner API to register a new store and specifies
'returnProfileId=true' in the request
- Ecwid returns the store ID 123 and the profile ID p98765 for the new store
- The partner saves the Ecwid profile ID in the user record to keep the link between
john@partner-sitebuilder.com and Ecwid profile ID p98765 in the system.
2) john@partner-sitebuilder.com requests to add a store to their another site — site B
- The partner checks if the user already has an Ecwid profile ID assigned. This time, the
Ecwid profile ID is there — it's p98765.
- The partner uses the Ecwid Partner API to register a new store and specifies
'profile_id=p98765 in the request
- Ecwid creates a new store and assigns it to the existing profile instead of generating a
new profile. The response specifies the new store ID 456. Now, two stores in Ecwid are
assigned to that profiel: store ID 123 and store ID 456.
3) john@partner-sitebuilder.com opens store control panels in the partner UI.
- The user manages the site A in one browser tab, and the site B in another browser tab
- To display the Ecwid control panel, the partner uses the Ecwid SSO API and passes the
profile_id parameter in request.
- The control panel A and the control panel B work simultaneously in different browser
tabs.
How to make it work for the existing users
Partner's existing Ecwid stores were registered before the above mentioned API became
available. All of those stores have different profile IDs assigned, even the stores of the same
customer are separate. To make the new approach working for the old users, the partner needs
to re-assign profile ID for those existing users who run several Ecwid stores.

Below is an instruction on how to do that for each particular user.

Partner finds Ecwid stores belonging to the user and their profile IDs
Partner should check the Ecwid stores belonging to a user and get their profile IDs. This can be
done via the /status endpoint of the Partner API. The profile ID field will present in the XML
response.

Request:
GET https://my.ecwid.com/resellerapi/v1/status

Response (XML):
…
<profileid>p987654321</profileid>
…

Partner assigns the same profile ID for all Ecwid stores belonging to the user
Now the partner has a list of stores and profile IDs assigned to them. Partner should choose any
of those profile IDs (e.g. the first one) and assign it to all stores of that customer, so that all
stores have the same profile ID.

To change the profile ID of the store, the Ecwid's Partner API /change-store-profile endpoint can
be used. It requires the following parameters:
- key: the Partner reseller key
- ownerid: the store ID
- src_profile: the old profile ID
- dst_profile: the new profile ID

The partner will get 200 OK in response if the profile ID has re-assigned.

Request:
POST
https://my.ecwid.com/resellerapi/v1/change-store-profile?ownerid=123&key=abc123
&src_profile=p98765&dst_profile=p55555
When it's done for all stores of the user, the new profile-based SSO API can be used as
explained above.

Note on security
When the same profile ID is specified for several stores, it tells Ecwid that the user associated
with that profile ID can manage all of those stores without extra login/password. So, partners
should be careful when assigning profile ID to avoid unintentionally giving a wrong user access
to the store data.