Adding a custom app to your Commerce Layer dashboard.
While most merchants use our APIs to power their storefronts and integrations, the back-office dashboard is where everyday operations happen. From orders to shipments to inventory, the dashboard groups all resources into apps that users can access depending on their roles and permissions.
What many don’t know is that you are not limited to the built-in apps. You can extend the dashboard with your own custom apps. This unlocks completely new workflows, tailored to your organization’s needs, while still leveraging Commerce Layer’s authentication and permission model.
This article explains how custom apps work, why you might need them, and how to add one to your dashboard.
Why custom apps matter
The dashboard comes with built-in apps like Orders and Shipments. Each app has a well-defined scope of resources and operations. For example, the Orders app works with markets, orders, and line items. A generated access token ensures the app can only request the resources it needs, with either full access, partial access or read-only mode. You can explore the predefined abilities for each app in the following documentation.
Sometimes your workflow goes beyond what the existing apps provide. Maybe you want to combine data from both orders and shipments. Maybe you want to build a dedicated reporting tool for your finance team. Or maybe you need an internal dashboard to manage marketing campaigns alongside promotions.
This is where custom apps come in. They give you full control over the experience while still integrating seamlessly with the dashboard’s authentication, roles, and permissions.
How custom apps work
When you add a custom app, it appears in the dashboard alongside the built-in apps. The difference is that clicking it opens a new browser window or tab, rather than loading inside the dashboard frame. Commerce Layer automatically generates an access token for the current user and appends it to your app URL as a query parameter:
https://your-app.com?accessToken=xxxx
Your app reads this token, authenticates requests against the Commerce Layer API, and applies the same permission model used by built-in apps. This means admins retain full access, while members are restricted to only the apps and abilities assigned to them.
If your app needs access to multiple resource groups at once, you can choose the generic app type. This generates an access token with permission to all resources, ensuring maximum flexibility.
Adding a custom app in the dashboard
You can add a new custom app in a few steps:
- Go to Developer > Custom apps in the dashboard.
- Click New custom app.
- Select the app type based on the resources you need (Orders, Shipments, or other built-in sets if you just need to customize one of those kinds of app — Generic, if your app requires access to multiple resource sets).
- Enter the app name and the URL where your app is served.
- Save and try it.
Your app is now listed in the dashboard. Any user with the right role can open it and start using it immediately.
Building a custom app
A custom app is simply a web application that you host yourself. You can build it with any framework or technology stack. All that matters is that your app can:
- Parse the
accessTokenparameter from the query string. - Use it to authenticate against the Commerce Layer API.
- Handle roles and permissions according to the token scope.
While you could start from scratch, we recommend using our open source dashboard apps as a base. They are built with React, TypeScript, Tailwind, and Vite.
By using this repo as your starter template, you inherit:
- The same look and feel as the dashboard.
- Built-in support for authentication.
- Pre-configured UI patterns and layouts.
On top of this, you can use our App Elements library.
This React components library powers our own apps and includes:
- Hooks for API calls.
- Components for lists, detail views, and forms.
- Styling consistent with the dashboard.
Beyond the basics
Once your custom app is running, you can iterate quickly. Some ideas:
- Create dashboards that aggregate data across multiple resources.
- Build custom workflows for customer service teams.
- Add internal-only tools without touching your storefront code.
Because everything is powered by Commerce Layer’s APIs and permission system, your custom apps remain secure and consistent with the rest of the platform.