NAV

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,
 "email": "john@store.com",
 "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_typebearer (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)
emailStore owner’s accountEmail, as provided in store profile
public_tokenPublic 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_typerequiredcode (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,
 "email": "john@store.com",
 "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_typebearer (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)
emailStore owner’s accountEmail, as provided in store profile
public_tokenPublic 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.