API access requires a platform where you can configure permissions and generate tokens. In Ecwid, we refer to this platform as an application. A private application that gives you access to store data through API is called a custom application. Learn how to get your first custom app.
Custom apps have a default configuration with limited permissions. For example, such apps cannot add new customers through REST API. To unlock additional features, you need to update the app configuration.
This article describes all the settings forming app configuration and gives instructions on how to update it.
Default app configuration
Configuration for all Ecwid apps consists of the following settings:
- Access scopes - a list of permissions defining API access for the app.
- Access tokens - non-expiring authorization keys for REST API requests.
- Endpoints - static URLs on the developer's server interacting with specific Ecwid APIs.
- App keys - unique and constant values used in request decoding and public app authentication.
When created, custom applications automatically get default access scopes and both access tokens unlocking some REST API requests. Both app keys are also automatically generated, though they have no use for a custom app with a default configuration.
All app settings are always available on the Ecwid admin > #develop-apps > Details page (read-only).
Access tokens
Ecwid requires an access token for authorizing REST API requests. Tokens do not have an expiration time, so once you have tokens, you can use them for as long as you need. However, depending on the data and HTTP request type, you need to use a token of the corresponding type.
There are two types of tokens, public and secret:
- Secret access tokens grant full access to store data, so their usage is limited to backend integrations and calls for security reasons. Do not expose secret tokens on the storefront. In API documentation, we refer to secret access tokens as
secret_tokenorSECRET_TOKEN. Token example:secret_EZWiLeBXWsGg82XH3SfSFfdw418QNBBM - Public access tokens grant access only to publically available data and actions: receiving details of enabled products and categories, placing orders without "Paid" status. Public tokens are safe to use on the storefront. In API documentation, we refer to public access tokens as
public_tokenorPUBLIC_TOKEN. Token example:public_B6mT2teCE55zT2jAeffLjzNJ4se3gfPj.
Every access token in Ecwid is unique. Therefore, a token grants API permissions for the application in only one store. Access tokens for the same application installed in two stores will always be different and won't be interchangeable.
Example of REST API request authorization:
curl --location 'https://app.ecwid.com/api/v3/STOREID/orders' \
--header 'Authorization: Bearer SECRET_TOKEN'
GET /api/v3/1003/profile HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer secret_PKV7a***EGEA
Access scopes
Access scopes define what API permissions the app gets when a user installs it. At that moment, Ecwid gets a list of enabled access scopes for the app and creates access tokens with matching permissions.
Changes in access scopes do not affect existing tokens, and they become unusable. After each update you’ll need to get new tokens with updated permissions. Check our guide on updating app settings below.
| Access scope | Notes |
|---|---|
| read_store_profile | Get store settings with REST API. Receive webhooks about changes in store settings or applications. Default scope for custom apps. |
| read_catalog | Get data about categories, products, product options, variations, and types with REST API. Receive webhooks about product and category changes. Default scope for custom apps. |
| update_catalog | Update product and category details, upload images and files to products, and delete products or categories with REST API. Default scope for custom apps. |
| create_catalog | Create new products and categories with REST API. Default scope for custom apps. |
| read_orders | Get data about orders placed in the store and abandoned carts with REST API. Receive webhooks about changes in carts and orders. Default scope for custom apps. |
| update_orders | Update order details, change order status, cancel and delete orders, and convert carts to orders with REST API. Default scope for custom apps. |
| public_storefront | Get a public access token for the app. Default scope for custom apps. |
| read_store_profile_extended | Get extended store settings like billing and channel information with REST API. |
| update_store_profile | Update store settings, manage logo images, and close storefront for maintenance with REST API. |
| read_store_limits | Get store limits and restrictions with REST API. |
| read_store_stats | Get store reports with REST API. |
| update_catalog_batch_delete | Delete all products from the store with REST API. |
| create_orders | Create new orders with REST API. |
| add_custom_blocks | Build custom Instant Site sections and templates that open new opportunities for creating custom UI/UX for websites built with Ecwid. |
| read_customers | Get data about store customers and customer groups with REST API. Receive webhooks about customer changes. |
| update_customers | Update customer or customer group details and delete them with REST API. |
| create_customers | Create new customers with REST API. |
| read_discount_coupons | Get data about discount coupons with REST API. Receive webhooks about discount coupon changes. |
| update_discount_coupons | Update discount coupon details with REST API. |
| create_discount_coupons | Create new discount coupons with REST API. |
| read_promotion | Get data about advanced discounts with REST API. Receive webhooks about advanced discount changes. |
| update_promotion | Update advanced discount details and delete them with REST API. |
| create_promotion | Create new advanced discounts with REST API. |
| read_reviews | Get data about product reviews with REST API. Receive webhooks about product review changes. |
| update_reviews | Update product review status and delete reviews with REST API. |
| customize_storefront | Get access to Storefront JS API and Checkout API (cart management and checkout extra fields). Modify the storefront with a custom JavaScript code running from your file. Requires customJsUrl endpoint to function. Optional endpoint: customCssUrl. |
| add_to_cp | Add a user settings page for the app. Requires iframeUrl endpoint to function. |
| add_shipping_method | Get access to Shipping API. Add a new shipping method with live rates on the checkout to the store. Requires shippingUrl endpoint to function. |
| add_payment_method | Get access to Payment API. Add a new online payment method to the store. Requires paymentUrl endpoint to function. |
| customize_cart_calculation | Calculate Live discounts or Live surcharges on the checkout. Requires cartPromotionsUrl endpoint to function. |
| buy_domains | Purchase and manage store domains with REST API. |
| read_invoices | Get data about order invoices. Receive webhooks about changes in order invoices. |
| read_brands | Get data about product brands with REST API. |
| read_subscriptions | Get data about purchased subscription products with REST API. |
| update_subscriptions | Update subscription details with REST API. |
| charge | Charge users for your application through Ecwid billing. For public apps only. |
| read_staff | Get data about staff accounts in a store with REST API. |
| invite_staff | Send and resend staff account invites with REST API. |
| create_staff | Create staff accounts with REST API. |
| update_staff | Update staff account details with REST API. |
| delete_staff | Cancel the invite for the staff account and delete it with REST API. |
Endpoints
Some API features require you to set up a live server listening to incoming requests. For example, Ecwid requires a URL to send webhooks. To work with such features, you need an endpoint - a static URL working on your server that can handle HTTP requests.
List of available endpoints and related features:
webhookUrl: Webhooks about events happening in the store.paymentUrl: Payment API for adding online payment methods for the store.shippingUrl: Shipping API for adding live shipping rates for the checkout.cartPromotionsUrl: Live discounts for adding custom live discounts to the checkout.customJsUrl: Storefront customization with JavaScript code.customCssUrl: Storefront customization with CSS code.iframeUrl: Native app for creating a user settings page.
Application keys
App keys are used in Payment API and app authentication. Values for app keys are unchangeable and unique for each application. There are two app keys:
client_id- Unique application ID.client_secret- Application secret used for decryption in authentication and Payment API.
Access to REST API or storefront/checkout customizations does not require app keys.
How to update app configuration
Ecwid allows you to combine all settings listed above to create complex multi-functional apps. If you want to add several new or even all REST API scopes and several endpoints to one custom app, you can do so.
Ecwid API Support team updates all applications. If you want to change scopes, endpoints, or any other settings in your app, please request an update:
- Go to the Ecwid admin > #develop-apps > Details page.
- Scroll down to the Contact button:
- In the opened form, describe the changes and submit the form to us.
- Wait for the response from the API Support team. You'll get an email to your store registration address. We prioritize application update requests, so it should take less than a working day.
Note: access scope changes do not affect existing tokens. If you requested new access scopes, reinstall the app once you receive an email from API Support confirming that the app is updated. To do so, uninstall the app from the Ecwid admin > My apps page and install the app back from the Ecwid admin > #develop-apps > Details page. As a result, old access tokens become unusable, and you get new tokens with updated permissions.
If you are unsure what app configuration you need, describe your project in the update request. We'll help you with setting up the app.