Billing, App Store and Deployment

Three billing models are supported, and a plan can combine the first two.

Plans are either public or private. Public plans are visible to every merchant, on the plan selection page and in the App Store listing, and an app can have up to eight of them. Private plans are offered only to the stores listed on the plan (the store domains such as example.myshopify.com), they are not translated, they appear on the plan selection page only for a logged-in user of an authorized store, and an app can have any number of them as long as no store is authorized for more than eight. A plan’s billing model (price, intervals, trial) is edited separately from its description (display name and top features), because descriptions are localized: a plan is shown to merchants only when it has a description in the language of the listing the merchant sees.

The plan editor has these fields:

A downgrade from a paid plan to a free plan is deferred: it takes effect at the end of the paid plan’s current billing cycle.

Source: Shopify: Public and private plans

A new public app uses Shopify App Pricing by default when it is submitted. An existing app without active paid merchants can opt in, and an app that already bills through the Billing API follows the migration described later. The setting lives in the Partner Dashboard and not in the Dev Dashboard: when an organization has moved its apps to the Dev Dashboard the app’s configuration, monitoring and logs moved with it, but the App Store listing and its pricing stay in the Partner Dashboard. The path is App distribution, the app, Distribution, Manage listing beside Shopify App Store listing, Edit for a published language, Manage under Pricing content, Settings, and then Shopify App Pricing under Pricing method, followed by the default billing frequency (monthly or yearly; merchants can still toggle between the two). Plans created earlier with the Billing API that are not compatible with App Pricing have to be removed before the switch is possible. Once an app has opted in, it can no longer create new recurring application charges with the Billing API, while charges created before the switch keep being processed.

The plan page lives in the Shopify admin at this address, where the store handle is the part of the shop domain before .myshopify.com and the app handle is the handle of the app configuration.

Source: Shopify: Shopify App Pricing, plan selection page

An embedded app runs in an iframe and cannot redirect the parent window, so it has to ask the framework to navigate the top window. In the React Router package this is the redirect returned by authenticate.admin, called with target: "_top". The redirect belongs in the loader of the root route of the app, so that it applies whichever route the merchant arrives on, and the check that decides it must distinguish "no subscription" from "the lookup failed": a throttled or failed Partner API call has to throw instead of being treated as a missing subscription, otherwise a paying merchant is sent back to the plan page.

After the merchant approves a plan, Shopify redirects to the plan’s welcome link. For apps that have a landing page in App Home the link is a relative path such as /welcome and Shopify appends the plan_handle of the plan the merchant is subscribed to. For other apps the link is a full URL with a protocol, and both plan_handle and the shop domain (shop) are appended. The parameter is a hint and not a proof: the app has to confirm the subscription with the Partner API before it unlocks anything. Apps enrolled before April 2026 used to receive a charge_id, which no longer exists since 2026-04-28.

With Shopify App Pricing the subscription state does not come from the GraphQL Admin API but from the Partner API, which is a different API with different authentication. The Partner API belongs to the Partner organization and not to a store. Requests go to https://partners.shopify.com/{org_id}/api/2026-10/graphql.json, where the organization id is the number in the Partner Dashboard URL, with the header X-Shopify-Access-Token set to the access token of a Partner API client. A Partner API client is created by an organization owner under Settings, Partner API clients, and its permissions decide what it can read: View financials (transactions and cancelling App Pricing subscriptions) and Manage apps (app resources and events, which activeSubscription needs). The limit is four requests per second per client, after which requests answer 429 with the message "Too many requests". The activeSubscription query works only for public apps, and it returns null when the shop has no active subscription, through App Pricing or through the Billing API.

Source: Shopify: Shopify App Pricing, query subscription data

This query is copied from Shopify’s documentation. The Partner API schema is not published at an anonymous introspection address (the address pattern that works for the Admin and Storefront APIs answered 404 for the Partner API), so unlike the other GraphQL on this page it could not be validated against a schema, and the Node client below was exercised only against a local stand-in server that answers with the shape the documentation shows. Both the appId (gid://shopify/App/1234) and the shopId (gid://shopify/Shop/5678) are global ids; the shop id is read from the Admin API with { shop { id } }.

The history of an app is a second Partner API query, the root events field. It returns installs, uninstalls, plan changes, cancellations, freezes, charges, earnings and credits in reverse chronological order, filtered by eventTypes, by subjectId (the app) and shopId (a filter by shop requires the app id as well), and by subjectType: APP. It returns the last 30 days unless occurredAtMin and occurredAtMax widen the window to at most 365 days, and pages of at most 250 events are read with first and after. The subscription lifecycle types are SUBSCRIPTION_CREATED, SUBSCRIPTION_UPDATED, SUBSCRIPTION_CANCELLATION_SCHEDULED, SUBSCRIPTION_CANCELED, SUBSCRIPTION_FROZEN and SUBSCRIPTION_UNFROZEN; charge events are CHARGE_RECURRING, CHARGE_ONE_TIME and CHARGE_USAGE; the others are credits (CREDIT_APPLIED, CREDIT_FAILED, CREDIT_PENDING), earnings (EARNING_CHARGE_RECURRING, EARNING_CHARGE_ONE_TIME, EARNING_CHARGE_USAGE, EARNING_CREDIT, EARNING_REFUND, EARNING_ADJUSTMENT) and the relationship events (RELATIONSHIP_INSTALLED, RELATIONSHIP_UNINSTALLED, RELATIONSHIP_REACTIVATED, RELATIONSHIP_DEACTIVATED). An older App.events field uses a different enum (AppEventTypes, with names such as SUBSCRIPTION_CHARGE_ACCEPTED); new integrations use the root events query.

The Node module below is the whole App Pricing integration of Roast Badge outside the framework: the Partner API lookup, the App Events token and the event sender. It validates the documented limits of an event before sending it (handle characters, 64-character idempotency key, at most 15 attributes of 64-character keys and scalar values, non-zero value that is either an integer or a quoted decimal), retries 409, 429 and 5xx answers with the same idempotency key (which is what the key is for) and caches the 60-minute token for 55 minutes.

Source: Shopify: App Events API reference and Shopify: Partner API reference

The module was exercised with a test that starts a local HTTP server on 127.0.0.1 and plays the three Shopify endpoints (/auth/access_token, /app/2026-10/events and the Partner API path). It asserts that the Partner request carries the token header and the activeSubscription query, that the event request carries a Bearer token and the same idempotency key on the retry after a first 429, and that eight invalid events are rejected before any request is made (a reserved shopify. handle, a handle with a space, a 65-character key, a nested attribute, 16 attributes, 1.5, 0 and "abc" as value). All assertions passed. Nothing was sent to Shopify, and the placeholder- tokens in the test are not real.

Source: Shopify: Build a billing event

In a React Router app the lookup goes in the loader of app/routes/app.tsx, as Shopify’s documentation shows. The example below follows the documentation: it reads the shop id through the Admin API, asks the Partner API, redirects to the plan page with target: "_top" when there is no subscription, and throws on any failure of the lookup. The environment variables are the organization id, the Partner API token and the app’s GID, and the documentation recommends caching only a confirmed subscription per shop for a short time such as five minutes, so that a merchant who has just approved a plan is checked again immediately while a cancellation or a freeze is still noticed soon. This route was not executed, because it needs a Partner API client and an installed app.

Source: Shopify: Redirect to the plan selection page

activeSubscription returns Billing API subscriptions too, so subscriptions that have not been migrated yet need no separate check. One-time purchases are not subscriptions: when existing one-time purchases grant access, the app must also call billing.check(), which reads currentAppInstallation and answers hasActivePayment: true for an active one-time purchase, until no such purchase remains.

Shopify App Pricing does not use webhooks to tell the app that a subscription changed. Until 2026-04-28 an app enrolled before April 2026 could subscribe to APP_SUBSCRIPTIONS_UPDATE; after that date none is sent, and charge_id is gone from the redirect. The replacements are the redirect parameters, for changes that follow a merchant action, and the Partner API for everything else.

Source: Shopify: Shopify App Pricing, subscription change notifications

An app therefore cannot be purely event-driven. A job that re-checks the subscription of every installed shop at an interval the business can live with (the Partner API allows four requests per second, so a daily pass over a few thousand shops is cheap) closes the gap between a freeze or a cancellation and the next time the merchant opens the app.

A metered plan needs two halves that are joined by one string. In the Partner Dashboard the plan has a meter whose handle is, for Roast Badge, labels_printed; in the app, every printed label is reported to the App Events API as an event whose event_handle is exactly labels_printed. Handles are case sensitive, and a mismatched handle makes the event non-billable in the Dev Dashboard rather than failing the request. All events, billable or not, are visible in the Dev Dashboard under Logs, and the filter Type, App Billing Event shows only those tied to meters.

The pricing structures differ in how the total is computed from cumulative usage. With the tiers 1 to 100 units at USD 10, 101 to 200 at USD 9 and 201 or more at USD 8, graduated pricing charges each tier at its own rate, so 150 units cost 100 x 10 + 50 x 9 = USD 1,450, while volume pricing charges the whole quantity at the rate of the tier it falls in, so 150 units cost 150 x 9 = USD 1,350. Fixed pricing charges one price per unit, for example USD 0.05 per label. Usage billing requires the monthly cycle, so a usage meter cannot be attached to a yearly-only plan, and usage caps do not exist.

Authentication uses the client credentials of the app, from the Dev Dashboard. A POST to https://api.shopify.com/auth/access_token with client_id, client_secret and grant_type: "client_credentials" returns a JWT access token (token_type is always Bearer) that lasts 60 minutes, and the request must carry a User-Agent header, because a 403 with the message "You do not have permission to access this website" is the symptom of a missing one. The permission to write App Events is included automatically in the reference, while the billing tutorial lists an API key with the write_global_api_app_events scope among its requirements; the two statements are in Shopify’s pages as written, and an app that gets a 401 or a 403 after the user agent is set should check that scope first. Events are posted one at a time to https://api.shopify.com/app/2026-10/events (the tutorials still show /app/unstable/events) with the header Authorization: Bearer <token>.

Events must not contain data that identifies a person (names, e-mail addresses, phone numbers, customer ids, addresses); anonymized ids and aggregates are the rule, and the App Events API terms forbid personal information.

The answers are these. 202 Accepted means that the request was received, not that billing accepted it: billing errors are processed asynchronously, there is no synchronous billing error and no webhook for one, and the only place to see them is the Dev Dashboard log. 400 is an invalid request, 401 a missing or invalid token, 403 an app that is not installed on the shop or an invalid shop_id, 409 a request with the same key still being processed (retry after a short delay), 429 the limit of 500 requests per second per app, and 5xx an internal error.

Source: Shopify: Setup usage charges

Three consequences follow for the design of the sender. The event has to be created where the usage happens and queued, so a failure of the network does not lose it, and because idempotency of billing events is permanent, a stable key derived from the business event (label-1001-1 for the first label of order 1001) is safe to retry for as long as needed. A correction is a second event with a negative value, a new key and a timestamp in the current cycle, never a repeat of the first event. And the uninstall webhook is the signal to flush the queue: the app has 24 hours after an uninstall, and not a minute more.

Source: Shopify: App Events API reference

On a development store of the same Partner organization as the app, every plan available to the store can be selected at no charge. Across organizations only free plans and paid plans that the developer marked "free for partners and developers" are available. Selecting a paid plan creates an app subscription contract whose effective recurring and usage prices are zero, which is enough to check usage meters, welcome links and billing events. A private test plan of USD 0 exists in the Private plans section for developing the integration before any public plan is published or to limit testing to chosen stores. The Billing API test flag must not be used for App Pricing tests. Before 2026-04-28 a selected plan on a development store created a test subscription; that behaviour no longer applies. A known limitation: while an app is in draft, its plan page can answer 404 when the development store and the listing have different locales, which does not affect production stores or published apps.

Upgrades and downgrades are new subscriptions that go through the same flow. A pending charge that the merchant does not approve within two days becomes EXPIRED.

The mutation below creates the Pro plan of Roast Badge: a recurring USD 9 charge every 30 days and a usage line item of USD 20 cap with the terms shown to the merchant. lineItems takes one pricing plan of each type, so a subscription holds at most one recurring and one usage line item. trialDays starts on the day the merchant approves, test marks the charge as a test transaction, and replacementBehavior (not used in the document below) decides what happens when the merchant already has a subscription: APPLY_IMMEDIATELY cancels the old one at once, APPLY_ON_NEXT_BILLING_CYCLE defers both the cancellation and the new one to the next cycle (and is ignored when the currency differs), and STANDARD is the default that replaces immediately except in the documented cases where the replacement is deferred.

The variables for the Pro plan, in JSON, with test set to true so that no charge is made while the integration is tested:

Source: Shopify: appSubscriptionCreate

The document validates against the Admin schema 2026-10. The variables were coerced against the variable definitions with the same schema: they are accepted, while a copy with "interval": "MONTHLY" is rejected with "Value "MONTHLY" does not exist in "AppPricingInterval" enum", because the only intervals are EVERY_30_DAYS and ANNUAL. The call itself was not made, because it needs an installed app and an access token.

The response holds confirmationUrl and userErrors. The app redirects to confirmationUrl only when userErrors is empty. The status of the new AppSubscription is PENDING until the merchant approves it.

AppPurchaseStatus, the status of a one-time purchase, has PENDING, ACTIVE (approved and charged immediately), DECLINED, EXPIRED (not accepted within two days) and the same deprecated ACCEPTED.

The next three operations cover the rest of the Billing API. A one-time purchase (a pack of printed labels, for instance) takes a name, a price, a return URL and the test flag. A usage record is created against the usage line item of an active subscription; it takes the line item id, a price, a description and an optional idempotencyKey of at most 255 characters, and it counts toward the capped amount. A cancellation takes the subscription id and an optional prorate flag: when it is true, Shopify issues prorated credits to the merchant for the unused part of the period and deducts the corresponding amount from the Partner account.

Source: Shopify: Support one-time app purchases

All three documents validate against the 2026-10 schema, and the variables of the one-time purchase and of the usage record are accepted. A usage record counts toward the capped amount of its subscription; raising the cap is a separate mutation, appSubscriptionLineItemUpdate(id, cappedAmount), which returns a confirmation URL that the merchant must approve. appSubscriptionTrialExtend(id, days) extends the trial of an existing subscription by 1 to 1000 days; it fails with the codes SUBSCRIPTION_NOT_FOUND, TRIAL_NOT_ACTIVE or SUBSCRIPTION_NOT_ACTIVE.

Source: Shopify: appSubscriptionTrialExtend

The adjustments that the Billing API supports besides the trial are app credits (a sum the merchant can apply to future purchases, subscriptions or usage, created with the Partner API), subscription discounts (a percentage or fixed amount for a set number of billing cycles, for new subscribers and for existing ones), and refunds of a specific charge, full or partial. The Admin API of version 2026-10 has no credit mutation; the mutations of the billing family are appSubscriptionCreate, appSubscriptionCancel, appSubscriptionLineItemUpdate, appSubscriptionTrialExtend, appPurchaseOneTimeCreate and appUsageRecordCreate.

The state of an app’s charges is read from the installation of the app in the shop. The query below reads the active subscriptions, the last ten subscriptions of any status, the one-time purchases and the merchant’s local billing currency. activeSubscriptions replaces the field subscriptions, which is deprecated.

Source: Shopify: currentAppInstallation

The query validates against the 2026-10 schema, and the same document with the singular field activeSubscription is rejected with the message Cannot query field "activeSubscription" on type "AppInstallation". Did you mean "activeSubscriptions", "allSubscriptions", or "subscriptions"?, which is the typo that most often appears in code written from memory. The query shopBillingPreferences returns the merchant’s local billing currency, which is the currency in which a Manual Pricing charge can be created when the currency is one of those that Shopify supports for local billing.

The three webhook topics of the Billing API exist in the topic enum of the 2026-10 schema: APP_SUBSCRIPTIONS_UPDATE (the status or the capped amount of a subscription changed), APP_PURCHASES_ONE_TIME_UPDATE (the status of a one-time purchase changed) and APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT (the balance used crossed 90% of the cap). They are subscribed like any other topic, in shopify.app.toml or with the Admin API as below, and the delivery has to be verified and answered as the page on webhooks and events describes. Because webhooks can take minutes to arrive, an app must not rely on them alone to unlock a plan: the redirect to the returnUrl and a read of the installation are the immediate signals, and the webhook is the late confirmation of changes that happen outside the app, such as a freeze for non-payment.

Source: Shopify: About manual pricing

The uri field of the webhook subscription input is a String, so the variable that feeds it is a String! and not a URL!: typing it as URL! is a common mistake that the schema reports as a variable used in a position that expects the type String.

The React Router package wraps these calls. The pricing model is declared in the billing option of shopifyApp, as an object whose keys are plan names and whose values are one-time (amount, currencyCode, interval: OneTime) or recurring and usage (lineItems of recurring or usage items, optionally with trialDays, replacementBehavior and a recurring discount). The helpers are then called on the object that authenticate.admin returns: billing.require checks for an active payment for any of the plans and runs onFailure (typically billing.request or a redirect to the plan page) when there is none, billing.check answers hasActivePayment and the list of subscriptions without failing, billing.request creates the charge and throws a redirect to the confirmation URL, billing.cancel cancels a subscription, billing.createUsageRecord creates a usage record and billing.updateUsageCappedAmount raises the cap. The documentation calls the whole group the Manual Pricing helpers.

The configuration of Roast Badge, the one plan of each kind:

Source: Shopify: React Router billing API

A route that shows the plan, requests the charge and cancels it:

Source: Shopify: About manual pricing, request payment

A route that is gated behind a plan and records the usage of one label:

Source: Shopify: About manual pricing, gate requests

The three files were type-checked in a copy of the official React Router template (react-router typegen, then tsc --noEmit with the strict settings of the template) and compile without errors. The check is stricter than it looks: the plans option is typed from the keys of the billing configuration, and changing one plan name in app.labels.tsx to a string that is not configured makes the compiler reject it ("Type '"Nope"' is not assignable to type '"Roast Badge Pro (monthly)" | "Roast Badge Pro (annual)" | "Roast Badge labels" | "Roast Badge starter pack"'"). The loader of the gated route is the pattern to copy to every loader and action that serves a paid feature, because a route that is not gated can be requested directly; Shopify recommends a layout route (the template’s app/routes/app.tsx) when several routes are gated. These routes were not executed, because they need an installed app.

isTest is the helper’s name for the test flag. A test charge is never billed, and a development store cannot be charged in any case; the flag must be false in production, or the merchants who install the published app are not charged at all. The example derives it from NODE_ENV, so a production build cannot ship with the flag on by accident.

Most requirements are about the listing or about product behaviour. The ones below are decided by how the app is built, and they are the ones that connect to the rest of this section. The right-hand column says how a team can check each one before submitting.

Source: Shopify: App Store requirements

Four dated rules from other parts of this section are enforced through these numbers. Script tags are blocked from creation on 2026-10-01 and stop running on online store pages on 2027-03-01, which is why 5.1.1 asks for theme app extensions (see theme app extensions and web pixels). Expiring offline access tokens have been required for new public apps since 2026-04-01 and are required for all public apps from 2027-01-01. The three compliance webhooks (customers/data_request, customers/redact, shop/redact) are mandatory for public apps. And Built for Shopify apps have until 2027-05-01 to match the new admin design in App Home with Polaris 2.0. The timeline of these and the other deprecations is on the page about what is new and the deprecation timeline.

An app created as public starts in the Draft status. The review page in the Partner Dashboard lists the issues that must be fixed before the Submit your app button works. After submission the status is Submitted and an e-mail confirms receipt; the developer can withdraw at any time. If a core requirement stops the reviewer from reviewing, the app moves to Paused with an e-mail that lists the changes, and Submit fixes resubmits it. Once a reviewer is assigned, an app that needs fixes that must be discussed moves to Reviewed, and the developer replies to the e-mail to continue. When the review team approves the app, the status becomes Published and the app appears in the Shopify App Store. By default every approved listing is visible; the requirements are the same for fully visible and limited visibility public apps.

Source: Shopify: About the app review process

The diagram condenses the statuses that Shopify names (Draft, Submitted, Paused, Reviewed, Published) and the transitions that the review page describes. Withdrawing a submission is possible at any point from the status banner and is not drawn.

Before the app is submitted Shopify expects it to be production-ready, and the "Pass app review" guide turns that into a routine:

The table of common review problems is the shortest summary of what makes reviews fail.

Source: Shopify: Pass app review

Built for Shopify (BFS) is the highest level of recognition and sits on top of the requirements: the app must meet a set of achievement criteria that are evaluated automatically on a regular basis and, once the prerequisites are met, the developer applies from the Distribution page of the app (the person who applies needs the Manage apps permission). The benefits are a highlight and a badge on the listing and on app cards, a search filter and a search ranking boost, priority app review for the developer’s later apps, plan-based targeting for App Store ads, and eligibility for the App Store home and category pages, the Picked for you modal in the admin and story pages. The app review team handles the application; a criterion that fails three times in a row suspends the application for three months. BFS apps are reviewed annually, and an app that no longer meets the standards has 60 days after the e-mail to fix the failures. Smaller achievements exist on the way (the highlights "Works with the latest themes" and "Use directly in the Shopify admin", for example), and dated BFS requirements include 2026-12-01 for returns and exchanges apps and for subscription apps, and 2027-05-01 for the new admin style.

Source: Shopify: About Built for Shopify

Shopify recommends a separate app for production. It may share the repository and the code of the development app, but it has its own record and its own configuration in the Dev Dashboard, with its own client id, so that development experiments, test installs, scope changes and webhook URLs never touch the app that merchants have installed. The CLI represents this with one configuration file per app record: shopify.app.toml for the linked development app and, for example, shopify.app.production.toml for the production app, selected with --config production (or -c production). shopify app config link creates a file by linking it to an existing app, and --client-id together with --config deploys a configuration to a different app than the one it is linked to. The distribution method (public or custom) is chosen on the production app.

Extensions are matched with Shopify’s records through a UID in each shopify.extension.toml. UIDs are source-defined, scoped to the app and deterministic for a given extension handle, so the same extension has the same UID in the development, staging and production apps. They are added automatically when an extension is generated and when shopify app deploy runs. This is how a deploy knows which extensions were added, updated or removed.

An app version is a snapshot of the app configuration and all the extensions. Creating one from the CLI takes the local configuration file and the local extensions: an extension that exists in the deployed app but not in the working tree is not part of the new version, which in practice means that it is removed from the app. A version created on the version create page of the Dev Dashboard contains the configuration of that page and the extensions of the current active version, and it cannot add or change extensions, which can only be deployed from the CLI. Releasing a version replaces the version that every install is served, and merchants are upgraded within several minutes. Releasing an older version reverts. Depending on the extension types that a version contains, Shopify can require a review before the version is released.

The consequences for a pipeline are three. Deploy is all-or-nothing: the command deploys everything in the project, never only some extensions and never only the configuration, and the old shopify app config push command is no longer supported (the guidance is to update the configuration with deploy). Extensions are removed when they are missing from the checkout, which is why a shallow clone or a path filter that drops a directory can delete an extension and its data on stores. And a version is a unit of rollback: keeping every release as a version makes the previous state a command away.

Source: Shopify: Deploy app versions

The flags of shopify app deploy, read from the installed 5.0.0 CLI, with the environment variable that each one can be set by (the variables are how a pipeline passes them without editing the command):

Source: Shopify CLI: app deploy

The old --force flag of deploy and release was removed in CLI 4.0.0 (2026-05-21); --allow-updates and --allow-deletes replace it. shopify app release accepts --version (required), --allow-updates, --allow-deletes, --config, --client-id, --json, --no-input, --path and --reset, and in a non-interactive environment it needs one of the two allow flags as well.

The web app runs on a host that supports the runtime of the template (Node.js for the React Router template, which ships a Dockerfile). Shopify’s deployment guides cover Vercel, Google Cloud Run, Fly.io and Render, and a manual guide for any service that runs JavaScript. Three values connect the hosted app to the Shopify configuration: application_url, the redirect_urls of [auth] and the webhook uri entries, and all three are part of the version that shopify app deploy releases. Two sequencing rules follow. The web app must be deployed first, because the new configuration may point Shopify at a route that does not exist yet, and releasing the version before the routes exist leaves Shopify sending webhooks and redirects to missing routes. And a database migration that the old and the new code can both live with (the template’s prisma migrate deploy step) belongs before both, because there is a window of several minutes in which some installs are on the old version while the new web app is already serving.

The TOML validation of the CLI protects some of this before anything is sent. A webhook subscription with an http:// URI is rejected by shopify app build with a message that "URI format isn’t correct" and lists the valid formats: a relative path starting with a slash, an HTTPS URL, pubsub://{project-id}:{topic-id}, kafka://{topic-id} or an EventBridge ARN. A configuration without [auth], application_url or embedded fails with the messages Required, Valid URL is required and Boolean is required.

The CLI authenticates non-interactively with an app automation token, created in the Dev Dashboard: open the app, App settings, App Automation Token, Create token, choose an expiration of 1, 3 or 6 months, Generate token and copy the value at once, because it is shown only then (a lost token is revoked and replaced). Each token is scoped to the app on which it was created and can deploy only that app, so a production token cannot touch the development app or other apps of the organization. The pipeline gives the token to the CLI as the environment variable SHOPIFY_APP_AUTOMATION_TOKEN, and the CLI uses it automatically when it runs without a terminal.

Tokens expire, so there is a rotation procedure that does not interrupt deployments: Rotate creates a second token while the first stays valid, the CI secret is updated to the new value, and Revoke on the old token is the last step, after a pipeline run has proved the new token. Both tokens are valid until revoked, which is the window in which every environment is updated. The documentation describes no expiry notification, so a calendar reminder before the expiry date is the practical alarm.

Older pipelines used a token from the Partner Dashboard in SHOPIFY_CLI_PARTNERS_TOKEN. New ones can no longer be created there, existing ones work until they expire, and the migration is to create an app automation token, switch the variable name to SHOPIFY_APP_AUTOMATION_TOKEN, check a run and revoke the old token.

Source: Shopify: Manage app automation tokens

Shopify’s own example for GitHub Actions deploys on every push to main. It is reproduced here exactly as published because the workflows of this page are a revision of it.

Source: Shopify: Deploy app components in a CD pipeline

The example is the right skeleton and has five problems that a production pipeline should not inherit. actionlint 1.7.12 reports two of them as errors on the file above: actions/checkout@v1 and actions/setup-node@v3 are too old to run on GitHub Actions. The third is the Node version: the example sets up Node 18, while the Shopify CLI 5.0.0 requires Node 22.12 or later (the CircleCI example in the same guide uses Node 20.5.0, which is also below the requirement). The fourth is that the CLI is installed globally with @latest, so a major release of the CLI changes the pipeline without a commit; the CLI is a dependency of the template, so npx shopify after npm ci runs the version that the lockfile pins, and CLI 4.0 added auto-upgrade, which the CLI skips in CI and for project-local installs. The fifth is that the commit message, the token and the deletion policy are not considered: the example has no --version, no --message and no way to stop before releasing.

The guide also states the two flags that decide the safety of an unattended run. --allow-updates lets the deploy add and update extensions and configuration, and --allow-deletes lets it remove them; since deleting an extension or configuration also deletes related data on stores that have the app installed, only --allow-updates belongs in the default workflow and --allow-deletes (or SHOPIFY_FLAG_ALLOW_DELETES) in a manual run when something has to be deleted.

The first workflow runs on every pull request and every push to main. It needs no token, so it can run on pull requests from forks without exposing anything, and it catches the problems that review would otherwise find later: type errors, an invalid configuration, an unbuildable extension and the security findings of the deterministic scan.

Source: Shopify CLI: app security check

shopify app build --no-input --config production validates the TOML and builds every extension offline, and shopify app security check --no-input --config production --blocking high runs the deterministic scan and exits with a non-zero status when a finding of high severity (or above the chosen level) exists. --blocking accepts high, medium, low and none, and the default none never fails the job, which is why the flag is explicit in the workflow. persist-credentials: false keeps the GITHUB_TOKEN out of the checked-out repository’s git configuration, and permissions: contents: read gives the job nothing else.

The second workflow creates the version and then releases it in two jobs, which is the reason for --no-release: the version is created first, so that a deploy that Shopify rejects fails in the first job with nothing released, and the release itself waits for a person.

Source: Shopify: Deploy app components in a CD pipeline

How each part works, and why it is there:

Both workflows were checked with actionlint 1.7.12, which reports nothing for them; as a comparison it reports an undefined variable secret (a typo for secrets), a needs that names a job that does not exist and a missing output when the deploy workflow is deliberately broken in those two places. A YAML parser accepts both files and rejects an indented-wrongly copy with a parser error. The shell lines that build the commit message were run with bash for two inputs, a three-line commit message and an empty one, and produced the first line and the manual fallback. The steps of the pull request workflow ran against a copy of the official React Router template with the Pocket Coffee billing routes: npm-installed dependencies, react-router typegen and tsc --noEmit (exit 0), shopify app build --no-input --config production (built) and shopify app security check --config production --blocking high (exit 0, no findings). The deploy and release steps need a real app and token, and were not run.

The only secret of these workflows is SHOPIFY_APP_AUTOMATION_TOKEN, and the only way it appears in a workflow file is the reference ${{ secrets.SHOPIFY_APP_AUTOMATION_TOKEN }}. The rules that keep it that way:

Because every deploy creates a named version, the pipeline gives three operations that need no new tooling. shopify app versions list --config production shows what exists (the version tag, the status and who created it). A rollback is shopify app release --config production --version <previous> --allow-updates, which makes the earlier snapshot the active one for every install. A promotion between environments is the same repository deployed with another --config: a staging configuration that points to a staging app and a staging web host is the natural gate before production, and it is a second workflow_dispatch workflow or a second pair of jobs. Neither step reverts the web app or the database; the previous code has to remain compatible with the previous version for the rollback to be consistent.

Themes are not part of an app version. A theme is deployed with shopify theme push and a different credential: a Theme Access password, given to the CLI as SHOPIFY_CLI_THEME_TOKEN together with the store in SHOPIFY_FLAG_STORE (and SHOPIFY_FLAG_FORCE=1 to disable prompts), as described on the page about theme tooling and workflow. The two credentials are separate and belong to separate workflows, and the Pocket Coffee theme and the Roast Badge app can live in the same repository.

Source: Shopify: Deploy app components in a CD pipeline

Five security requirements are checked at review, and a vulnerability found during the review rejects the app until it is fixed.

Iframe protection is a sixth requirement with its own guide: an embedded app must send a frame-ancestors directive that allows only the authenticated shop’s admin to frame it (and 'none' for a standalone app). In the React Router template this is done by addDocumentResponseHeaders, called from the server entry.

Source: Shopify: Security requirements for App Store review

Shopify CLI 5.0.0 includes a scanner for the Shopify-specific part of this. The command has two halves. The deterministic scan runs locally with fixed code inspections for questions that have an exact answer, such as whether an API version is end of life or whether the compliance webhooks are configured. The agent review is a set of checks that code inspection cannot decide (is this query scoped to one shop?), which the command hands to a coding agent as instructions; the agent records its findings with shopify app security record and shopify app security review shows both halves combined. Without an agent only the deterministic half exists.

The documentation lists 37 checks: 25 of high severity, 10 of medium and 2 of low. The identifiers are stable and are what a finding quotes.

Source: Shopify: App security checks

The options that matter in practice:

Results are written to .shopify/app-security/<results key>/ (the results key is the configuration file name without .toml, or the client id) and are replaced by every run. shopify app security clean deletes them (--all for every directory). The command reports the number of findings, never their details, to Shopify as usage telemetry, unless analytics are turned off (SHOPIFY_CLI_NO_ANALYTICS=1, as in the workflows above). Some deterministic checks support only apps that follow the structure of the React Router template and @shopify/shopify-app-react-router; for other apps they are reported as unresolved and are left to the agent review (on the Pocket Coffee discount-only test app with a Function and no web app, the review said "11 checks unresolved" for exactly that reason).

The scan was run on the Roast Badge copy of the official template, with the billing routes of this page and a production configuration (shopify.app.production.toml: placeholder client id, https://roast-badge.example.com, the two uninstall and scope webhooks and the three compliance topics). Its result: 13 checks passed, 2 not applicable (APP_PROXY_LIQUID_INJECTION and LIQUID_UNSAFE_RENDER, because the app has neither an app proxy nor a theme extension), no findings, 23 files scanned, exit code 0 with --blocking high. Three deliberate mistakes were then added to a copy, and the same command found them:

With --blocking high the command exited with status 1 on that copy and with --blocking none with status 0, and the commented-out template configuration (without [auth], application_url and embedded) is refused before any scan with "Validation errors …​ Required". An .env file with a made-up secret in that copy was reported as passed by COMMITTED_SECRET, in line with the documented rule that files Git ignores are skipped (the template’s .gitignore lists .env); the check protects against a tracked secret, not against a leak by other routes. Nothing in the scan needed a login or a network.

Source: Shopify CLI: app security check

The practices below come from Shopify’s security guides. The "check" column names the tool or the manual test that proves the practice, which is the part that turns a list into a checklist.

Source: Shopify: About app security

Shopify’s guide for a security incident is a sequence, and it helps to have it in the repository before it is needed: contain the incident, revoke the credentials that may have leaked (an app automation token, a client secret, offline tokens, database and hosting credentials), preserve evidence, notify Shopify, work out which shops and which data were affected, fix the root cause, meet the legal obligations of the affected merchants and regions, and write the incident up.