Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 55 ยท Orientation

App Configuration with shopify.app.toml

Understand shopify.app.toml: app URLs, redirect URLs, access scopes, webhook subscriptions and how shopify app deploy turns configuration into app versions.

Every Shopify app has settings that live on Shopify's side: its name, the address of your server, the permissions it asks for, the webhooks it wants. In the past you edited these in a web dashboard, which made them hard to review and easy to break. Today the main place is a file in your repository, shopify.app.toml. This is configuration as code: the file is reviewed in pull requests, versioned in Git and applied with a command.

This lesson explains the important keys, how changes reach Shopify and how to avoid the classic mistakes. The TOML snippets are real but read-only here, since only the CLI can send them to Shopify. The runnable parts are stand-ins: a validator for a parsed configuration and a tiny model of app versions. Key names and defaults change over time, so use the CLI's generated file and the official configuration reference as the source of truth, and treat this lesson as the map.

What the file looks like

A trimmed file for an embedded app looks like this:

TOML
# shopify.app.toml (read-only sketch)
client_id = "0123456789abcdef0123456789abcdef"
name = "Tag Helper"
application_url = "https://tag-helper.example.com"
embedded = true

[build]
automatically_update_urls_on_dev = true

[webhooks]
api_version = "2026-07"

  [[webhooks.subscriptions]]
  topics = [ "app/uninstalled" ]
  uri = "/webhooks/app/uninstalled"

  [[webhooks.subscriptions]]
  topics = [ "app/scopes_update" ]
  uri = "/webhooks/app/scopes_update"

[access_scopes]
scopes = "read_products,write_products"

[auth]
redirect_urls = [ "https://tag-helper.example.com/api/auth" ]

The values above are examples. Your real file has your own client ID, which is the public identifier of the app. The client secret is not in this file: it lives in the environment, as you saw in Creating an App with the CLI.

The keys that matter first

Identity and URLs

  • client_id identifies the app on Shopify. It is public, and it ties this folder to one app record.
  • name is the app's name as merchants see it.
  • application_url is where Shopify loads your app: the address of your server's entry page. In development the CLI replaces it with the tunnel URL; in production it is your real domain. It must use HTTPS.
  • embedded says whether the app is displayed inside the Shopify admin (an iframe). Almost all new apps are embedded, and the authentication lessons assume it.

Redirect URLs

[auth] redirect_urls is an allow-list of addresses to which Shopify may send the browser after authorization. If your server asks to redirect somewhere not on the list, Shopify refuses. This protects against attackers who craft install links that deliver the authorization code to their own server. The OAuth Authorization Code Flow shows where it is used. Keep the list short and exact; do not add addresses you do not control.

Access scopes

[access_scopes] scopes is a comma-separated list such as read_products,write_products. These are the permissions merchants approve when they install the app. Ask only for what you use; Managed Installation and Access Scopes covers how to add scopes later and what merchants see.

Webhooks

[webhooks] api_version pins the API version used for deliveries from the app-specific subscriptions. Each [[webhooks.subscriptions]] entry lists one or more topics and a destination. The destination can be a path on your app URL (uri = "/webhooks/...") or a full address. Declaring subscriptions here means every shop that installs the app gets them automatically, without your code calling an API for each install. Webhook topics, delivery and security are covered from Webhooks in Shopify onward. Compliance topics for customer data are declared in the same section; see Privacy, GDPR and Mandatory Webhooks.

Build and development

[build] options influence the dev loop, such as whether the CLI should update the app URLs automatically when the tunnel changes. A dev_store_url can remember which store shopify app dev should use.

Other sections you will meet

The file grows as the app does: [app_proxy] for storefront proxy pages, [pos] for point-of-sale settings, and the extension folders have their own shopify.extension.toml files. Those arrive in the extension lessons.

How changes reach Shopify

Editing the file does not change the live app by itself. There are two paths:

  1. shopify app dev reads the file and applies a development copy of the configuration to your development setup. That is why changes show up quickly while you work, and why URLs follow your tunnel. This does not affect merchants.
  2. shopify app deploy creates a new app version from the current configuration plus all your extensions, and (by default, after a confirmation) releases it. Released versions are what installed merchants get.
flowchart LR
    F["shopify.app.toml<br/>+ extensions"] --> D["shopify app deploy"]
    D --> V["App version v7"]
    V -->|"release"| L["Live for merchants"]
    V -->|"not released"| H["Kept as a draft"]

Deploy bundles configuration and extensions into a version; releasing a version makes it live.

Because the version contains both configuration and extensions, you can review what changes between versions and roll back by releasing an earlier one. Some changes, like new scopes, need merchants to approve again; the platform handles that prompt for managed installs.

A practical rule: run shopify app deploy from your CI pipeline or a documented manual step, never ad hoc from a laptop on a Friday evening. Deploying Your App returns to this.

Multiple environments

It is common to have a separate app record for development, staging and production, each with its own client_id and URLs. The CLI supports several configuration files, such as shopify.app.staging.toml, and lets you choose one with the config flag or shopify app config use. This keeps test traffic away from real merchants. Check shopify app config --help for the commands your version offers.

Runnable stand-in: a configuration validator

You can check many configuration mistakes yourself before a deploy. The script below validates a parsed configuration (a plain JavaScript object, as produced by a TOML parser like the one in the previous lesson). The rules are examples chosen to teach, not Shopify's official validation, which is done by the CLI and the platform.

JS Validate an app configuration

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Treat checks like these as a safety net in CI. They catch typos before a deploy, but the platform is the final judge of what is valid.

Runnable stand-in: app versions

Versions are easy to understand once you can see them. This model keeps a list of versions, each a snapshot of configuration, with one marked as live. It shows a deploy, a release, and a rollback by releasing an older version. The real system keeps much more per version (extensions, who created it, notes), and these functions are inventions for teaching.

JS Deploy, release and roll back

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Mistakes to avoid

  • Using HTTP or localhost in production. Shopify loads embedded apps over HTTPS.
  • Forgetting redirect URLs after changing domains. Authorization breaks until the list matches your new address.
  • Asking for broad scopes "just in case". Merchants see and judge the list, and reviewers do too.
  • Committing secrets. The configuration file has no secrets; keep it that way.
  • Editing settings in a dashboard and in the file. Pick the file as the source of truth, or the next deploy may overwrite the dashboard change.
  • Deploying without reading the diff. The CLI summarizes what changes. Read it, especially for scopes and webhooks.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the purpose of the redirect_urls list?

    Shopify only redirects to exact addresses you declared, which stops attackers from steering the authorization code to their own server.
  2. 2. What does shopify app deploy do?

    Deploy bundles the configuration and extensions into a version, which can then be released to merchants.
  3. 3. Where does the client secret belong?

    The toml file is committed and reviewed by many people. Secrets live in environment configuration.
  4. 4. Why declare webhook subscriptions in the toml file instead of calling an API on every install?

    Declared subscriptions apply to all installs, so your install code does not have to register them one shop at a time.
  5. 5. How can you undo a bad release?

    Versions are kept, so releasing a previous good version brings merchants back to it.

Summary

  • shopify.app.toml is the app's configuration as code: identity, URLs, scopes, redirect URLs, webhooks and build options.
  • shopify app dev applies a development copy; shopify app deploy creates an app version that you release to merchants.
  • Keep redirect URLs exact, scopes minimal and secrets out of the file.
  • Use separate app records and configuration files for development, staging and production.
  • The validator and the version history here are stand-ins that teach the ideas; the TOML and commands are real but read-only on this site.

Next: The OAuth Authorization Code Flow