A custom app gives one store an API access token, created straight from that store's admin panel. Use it when you want to connect your own store to the EasyStore API, and you don't need a Partner account, OAuth or an App URL.

What is a custom app?

A custom app is an API connection that a merchant creates for their own store, in Apps → Develop custom app in the EasyStore admin panel. EasyStore installs it into that store right away and shows its access token on the page. Your code then uses that token to call the EasyStore API.

Typical uses:

• Syncing products, stock or orders between your store and your own ERP, POS or warehouse system
• Scripts and reports that read your store's data
• An integration a developer builds for one specific client store

 ┌──────────────────┐  1. Create custom app,   ┌──────────────────┐
 │     Merchant     │ ───────────────────────► │  EasyStore Admin │
 │                  │     pick scopes          │ Apps → Develop   │
 │                  │                          │   custom app     │
 └──────────────────┘                          └────────┬─────────┘
                                                        │ 2. Shows the
                                                        │    access token
                                                        ▼
 ┌──────────────────┐  3. EasyStore-Access-Token  ┌─────────────────┐
 │ Your code / ERP  │ ──────────────────────────► │  EasyStore API  │
 └──────────────────┘     https://{shop}/api/...  └─────────────────┘

Partner app or custom app?

Both call the same EasyStore API with the same EasyStore-Access-Token header. The difference is where the app is created and how many stores can use it:

• Custom app: created by the merchant in their own store's admin. It works only for that store, and the token is shown on the page. No OAuth, App URL or Partner account.
• Partner app: created by a developer in the Partner Dashboard. Any number of stores can install it, by private link or from the App Store, and each store gets its own token through OAuth.

See the full comparison of all three options.

Create a custom app

Any merchant can create custom apps in their store's admin panel. You don't need a Partner account.

1. Log in to the store's admin panel and go to Apps.
2. Click Develop custom app, then Create custom app.
3. Enter a name that says what the integration is for, for example Warehouse stock sync.
4. Under API access scopes, tick only the permissions your code needs. See API access scopes for what each one allows.
5. Save. The page now shows the API access token, and an App credentials section with the App ID and App secret.

Shown on the page	What it's for
API access token	Send it in the EasyStore-Access-Token header on every API call. This is the only credential API calls need.
App secret	Verifies webhooks EasyStore sends you. It plays the same role as a Partner app's Client secret.
App ID	Identifies the app. You don't need it to call the API or verify webhooks.

Call the API

Send requests to your store's .easy.co hostname, with the token in the EasyStore-Access-Token header:

curl 'https://{shop}/api/3.0/orders.json' \
--header 'EasyStore-Access-Token: {access_token}'

Replace {shop} with your store's .easy.co hostname, for example example.easy.co. Use it even if the store has its own domain. Everything in Calling the API applies: the same base URLs, call limits and response codes. The Popular APIs page is a good place to start.

A request outside the scopes you ticked returns Permission denied. To fix it, tick the missing scope on the custom app page and save. You don't need a new token.

Receive webhooks

A custom app can subscribe to webhooks with its access token, the same way a Partner app does. EasyStore signs each webhook with the custom app's App secret, so verify the Easystore-Hmac-Sha256 header using the App secret as the key, as described in Webhook HMAC verification.

Change scopes or uninstall

• Change scopes: open the custom app, tick or untick scopes and save. The change applies to the existing token straight away.
• Uninstall: click Uninstall on the custom app page. The token stops working, and the app's webhooks, script tags and snippets are removed.

FAQ

I'm a developer building an integration for a client. Which one should I use?

If it's for that one client, ask them to create a custom app and send you the token and App secret through a secure channel, such as a shared password manager. Don't send them by plain email or chat. They can also give you access to their admin to create it yourself. If you plan to offer the same integration to other stores, build a Partner app instead, so each store can install it and you don't have to collect tokens by hand.

Does a custom app need a review?

No. Custom apps are never reviewed and never appear on the EasyStore App Store.

Can I turn a custom app into a Partner app later?

No. Create a new app in the Partner Dashboard, install it on the store through OAuth, switch your code to the new token, then uninstall the custom app.

Can one custom app access several stores?

No. Each custom app belongs to the store that created it. Create a custom app in each store, or build a Partner app.