A Shopify custom app is a specialized application developed exclusively for a single store, not published on the Shopify App Store, and installed directly by the store owner. This structure, preferred for one-to-one integrations with ERP systems, accounting software, or logistics platforms, requires a different token acquisition and authorization process compared to standard public app development.
This guide is intended for developers who want to develop custom apps for their own stores, as well as technical teams who want to connect a SaaS or enterprise system that will integrate with Shopify.
What is a Shopify Custom App?
A Shopify custom app is an application type written from scratch for the specific needs of a particular store, installed only on that store, and does not use Shopify's public app infrastructure (App Store, OAuth authorization flow). It provides programmatic access to the Admin API or Storefront API.
Mixing up the three Shopify app types is a very common mistake. The table below clarifies which structure to use in which scenario:
Situations where a custom app is ideal: ERP (SAP, Netsis, Logo) integration, custom logistics/shipping system connection, internal automation workflows, and data synchronization between trading platforms.
Private App to Custom App: Shopify's 2023 Change
Shopify completely disabled the private app system in January 2023. Prior to this date, store admins could generate an API Key and API Secret to gain direct access. This method is no longer available in the new system.
Critical Note: If you still have an integration using old private app credentials, Shopify will permanently disconnect it. Switching to a custom app is mandatory.
Why was this change made? From a security standpoint, the old private app system posed serious risks in API key management: there was no key rotation, scope control was lax, and there was no detection mechanism for credential leaks. The new custom app system closes these gaps with HMAC verification, scope limitation, and token tracking features.
Technical differences introduced by the change:
- Old: Direct requests using API Key + API Secret. New: Access_token obtained via OAuth 2.0.
- Old: API Password in the X-Shopify-Access-Token header. New: OAuth token in the same header
- Old: No token expiration. New: Offline token is persistent, online token is 24 hours
Shopify Custom App Token Types
There are two different API interfaces and two different token types associated with them in Shopify custom app development.
Most enterprise integrations require Admin API access tokens. The Storefront API is used for customer-facing front-end development (headless commerce, mobile apps) and does not provide access to the Admin API.
Offline vs Online Token Difference:
Offline tokens are for background processes, cronjobs, and server-to-server integrations. They remain valid as long as the application is not removed from the store. Online tokens are for flows that require a user session and expire after 24 hours.
Tip: If you are writing ERP or accounting integrations, always use offline tokens. A synchronization process running at midnight with an online token will silently fail when the token expires.
Why is the New Custom App System Complex?
At Nodus Works, the most common issue we hear from the other team when working with both 3rd party SaaS platforms and corporate ERP teams is: "How do we get the Shopify token?"
Shopify's new custom app system was designed to be secure for valid reasons, but this design has introduced significant setup complexity. The process is particularly unclear for backend or integration teams working with the Shopify ecosystem for the first time.
Sources of complexity:
1. Two different ways to obtain tokens. A custom app can be set up either directly from the Shopify admin panel or via the OAuth flow through the Partner Dashboard. Each requires a different token acquisition procedure. If you start without knowing which path to take, you could spend hours struggling with an incomplete setup.
2. Partner Dashboard configuration. If you choose the OAuth route, you need to create an app in the Partner Dashboard, define callback URLs, and specify scopes. An error in any of these steps leads to invalid_client or redirect_uri_mismatch errors.
3. Scope management. The requested scopes must match exactly in both the .env or configuration file and the Partner Dashboard. Even a small discrepancy will invalidate the token.
4. HMAC verification. Shopify expects you to verify the parameters returned in the callback with its own signature. Skipping this step creates a security vulnerability; not implementing it causes errors in production.
Obtaining a Shopify Admin API Token: Two Methods
Method 1: Direct Token from the Store Admin Panel
This method is only applicable if you are obtaining a token for your own store and have admin access to the store.
Steps:
- Log in to Shopify admin → Settings → Apps and sales channels
- Go to the Manage apps page → Click the App development option
- Create app → enter app name → create
- Switch to the API credentials tab
- Select the required Admin API scopes (e.g., read_orders, write_products)
- Install the app → Approve
- The Admin API access token is displayed only once; save it immediately
Warning: Shopify only displays this token once. You will not be able to access the token again after closing the page; you will need to uninstall and reinstall the app to get a new token.
Limitation of this method: it works for a single store. If you want to connect the same integration to multiple stores, you need to switch to the OAuth flow.
Method 2: Partner Dashboard and OAuth 2.0 Flow
This approach is used for SaaS products, agencies, and multi-store integrations. The application created via the Partner Dashboard can be set up for different stores using the OAuth flow.
Technical flow:
1. User → Redirected to the Partner Dashboard app page
2. The /auth endpoint is called with the store domain
3. The Shopify OAuth authorization page opens
4. User grants permission → Shopify redirects to the callback URL with the code
5. The server verifies the HMAC
6. The token endpoint is called with the code + client_id + client_secret
7. The access_token is returned → stored in the database
Implementing this flow from scratch is a process with a high margin for error, especially regarding HMAC verification and scope management.
Shopify App Token Generator: Our Open Source Solution
At Nodus Works, we developed a lightweight tool to solve this problem, which we encountered repeatedly in integration projects, and released it as open source:
github.com/nodusworkscom/shopify-app-token-generator
This tool runs the OAuth 2.0 flow locally and generates a persistent Admin API access token. You can obtain a valid token in just a few minutes without having to write a full OAuth implementation.
What does it do?
When you run the tool, a small Express server starts on localhost. You are redirected to Shopify's OAuth authorization page; after you approve, the code returned to the callback URL is automatically captured, HMAC verification is performed, and the access_token is displayed both in the terminal and in the browser.
Installation:
git clone https://github.com/nodusworkscom/shopify-app-token-generator.git
cd shopify-app-token-generator
npm install
cp .env.example .env
Fill in your .env file:
SHOPIFY_API_KEY=your_client_id
SHOPIFY_API_SECRET=your_client_secret
SHOP=your-store.myshopify.com
SCOPES=read_products,write_orders,read_customers
npm start
Go to localhost:3000 in your browser → Click "Install app" on the Shopify confirmation screen → The token will be displayed in the terminal and on the screen.
Prerequisites:
- Node.js v16 or higher
- Shopify Partner account (free)
- An app created in the Shopify Partner Dashboard
- Callback URL defined as http://localhost:3000/callback
Important: In the application settings in the Partner Dashboard, the base URL must be defined as http://localhost:3000 and the redirect URL as http://localhost:3000/callback. Otherwise, you will receive a redirect_uri_mismatch error.
For multiple stores: You can change the SHOP value in the .env file and repeat the process for each store. Each generated token is specific to that store.
This MIT-licensed tool can be used as a starting point for Shopify integration projects and as a practical reference for understanding the token generation process.
Custom App Security and Best Practices
Token security is the most critical aspect of integration. An Admin API access token grants permission to manage orders, customers, and products in your store.
Token storage: Store the token as an environment variable; never include it in source code or version control systems. Verify that you have added .env to your .gitignore file. In production environments, use Vault, AWS Secrets Manager, or a similar secret management tool.
Minimum scope principle: Do not exceed the scopes required for the integration. For a system that will only read orders, read_orders is sufficient; do not add write_orders or read_customers. Although Shopify allows you to narrow the scope list later, expanding it requires reinstallation.
HMAC verification: Do not accept the token without verifying the HMAC signature sent by Shopify in the OAuth callback. Implementations that skip this step become vulnerable to token theft attacks. Our token generator tool automates this step.
Webhook security: Also verify Shopify webhooks with HMAC. Do not process incoming webhook data without checking the X-Shopify-Hmac-Sha256 header.
For support on security and technical architecture issues in Shopify integrations, check out our Shopify integration solutions service.
Common Errors and Solutions
invalid_client error: The Client ID or Client Secret was entered incorrectly. Compare the credentials in the Partner Dashboard with the .env file.
redirect_uri_mismatch error: The callback URL does not exactly match the redirect URL defined in the Partner Dashboard. Even a trailing slash difference will cause an error: http://localhost:3000/callback and http://localhost:3000/callback/ are considered different.
invalid_scope error: One of the requested scopes is invalid or incorrectly written. Refer to Shopify's official scope documentation.
Token is a one-time display: If the token obtained from the admin panel is not saved, the application must be uninstalled and reinstalled. The token obtained via OAuth in the Partner Dashboard can be renewed by running the OAuth flow again.
HMAC verification failed: The Client Secret is incorrect or the query string parameters have been changed. The token generator tool performs verification automatically; in manual implementation, pay attention to the parameter order.
For more information about ERP connections and system integrations in Shopify integration projects, check out our Shopify ERP integration guide and Shopify integration article. For accounting system integration, see our Shopify invoicing and accounting integration content.
Frequently Asked Questions
What is the difference between a Shopify custom app and a private app? A private app is an old structure that Shopify removed in 2023. A custom app is the new system that replaced the private app and offers more secure token management. Your current private app credentials no longer work; switching to a custom app is mandatory.
Is the custom app token valid indefinitely? The offline access token remains valid permanently as long as the app is not removed from the app store. The online token expires after 24 hours. You must use the offline token for background integrations.
Can a Shopify custom app be developed for free? A Shopify Partner account is free. There is no additional fee for custom app development; however, the store you integrate must have an active Shopify plan. You can use a free development store during development.
How many stores can I connect with a custom app? A custom app created from the admin panel is specific to a single store. To connect to multiple stores, you need to set up a structure using the OAuth flow via the Partner Dashboard; in this case, a separate access token is generated for each store.
How do I choose between the Shopify GraphQL Admin API and the REST API? Shopify is actively developing the GraphQL Admin API and phasing out the REST API. We recommend building your new integrations on GraphQL. GraphQL solves the data over-fetching problem and offers more flexible querying.
Can I obtain a token without an OAuth flow? Yes. A custom app created through the Shopify admin panel generates tokens directly without requiring an OAuth flow. This method is only valid for your own store; OAuth is mandatory for setup in other stores.
How do I listen to Shopify webhooks through the custom app? After obtaining the custom app token, you can create a webhook subscription via the Admin API. Define an endpoint and listen for Shopify's POST submissions to that endpoint. Process each webhook request by verifying the X-Shopify-Hmac-Sha256 header.
Can the token generator tool be used in a production environment? The tool is designed to generate tokens; once you have a valid token, you no longer need the tool. The generated token can be used in production API requests. The tool is ideal for learning, quick token generation, and integration testing.
Conclusion
Shopify custom app development has become unnecessarily complex, especially with the new token system. Starting without knowing which token type to use and how to obtain it can waste hours.
Direct token acquisition from the admin panel is sufficient for single-store integrations. If you need to support multiple stores or integrate a third-party system, the OAuth 2.0 flow is unavoidable.
The open-source tool we developed, shopify-app-token-generator, reduces the most challenging step of this process—the HMAC-verified OAuth flow—to just a few minutes.
If you are seeking technical consulting, architectural design, or development support for your Shopify integration project, you can take advantage of our Shopify technical support and maintenance services or contact us directly.
