Working with shopify.app.toml files 

shopify.app.toml files are used to manage your Shopify app configuration settings.

For the full TOML schema and Shopify-specific settings, see Shopify's app configuration documentation.

In framework v1.7+, Gadget automatically creates and manages the primary shopify.app.toml file for each environment. If your app uses an older framework version, see pre-framework v1.7 behavior.

Primary TOML files Framework v1.7.0+ 

In framework v1.7+, Gadget manages one primary TOML file for each development environment and one primary TOML file for production.

For your production environment, the primary file is shopify.app.toml. Gadget will automatically update this production TOML file when a Shopify connection configuration is set in your production environment.

For each development environment, Gadget creates a primary shopify.app.<ENVIRONMENT>.toml file when you add a Shopify connection configuration in the editor.

These files include the Shopify app URLs, access scopes, and webhook subscriptions that Gadget manages for that environment:

shopify.<ENVIRONMENT>.app.toml
toml
Copy
# Learn more about working with Shopify TOML files with Gadget at http://docs.gadget.dev/

client_id = "<SHOPIFY-CLIENT-ID>"
name = "<YOUR-APP-NAME>"
application_url = "https://<YOUR-APP-SLUG>--<ENVIRONMENT>.gadget.app/api/shopify/install-or-render"
embedded = true

[auth]
redirect_urls = ["https://<YOUR-APP-SLUG>--<ENVIRONMENT>.gadget.app/api/connections/auth/shopify/callback"]

[access_scopes]
scopes = "read_products,read_orders"

[webhooks]
api_version = "2024-10"

[[webhooks.subscriptions]]
topics = ["products/create", "products/update", "products/delete"]
uri = "https://webhooks.gadget-services.net/shopify/v1?domain=<YOUR-APP-SLUG>--<ENVIRONMENT>.gadget.app"

[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "https://webhooks.gadget-services.net/shopify/v1?domain=<YOUR-APP-SLUG>--<ENVIRONMENT>.gadget.app"

Gadget will automatically provide the correct values for the required URL and ID fields.

Connecting a shopify.app.toml file to a Shopify app 

By default, Gadget will manage shopify.app.toml files and you will not need to interact with them.

If you are building Shopify extensions for your app, you will need to connect the correct shopify.app.toml to your Shopify app using ggt and the Shopify CLI.

1. Install and use Gadget's CLI, ggt, to pull your project down to your local machine.
2. Install the Shopify CLI locally and use it to sign in to your Shopify Partners account.
3. Run the yarn shopify:config:use:<ENVIRONMENT> command to specify the shopify.app.toml file that should be used for your Shopify app:

terminal
Copy
# for a development environment
yarn shopify:config:use:development

# for production environment
yarn shopify:config:use:production

4. Deploy your Shopify CLI app:

terminal
Copy
yarn shopify:deploy:development

# for production environment
yarn shopify:deploy

5. Connect to your existing Shopify app when prompted.

Webhook subscriptions Framework v1.7.0+ 

In framework v1.7+, webhook subscriptions are defined in your TOML file as [[webhooks.subscriptions]] entries.

Gadget automatically generates these entries when you enable Shopify models or configure Shopify webhook triggers on global actions in the editor.

Each [[webhooks.subscriptions]] entry can include the following fields (see Shopify's subscription configuration docs for full details):

Webhook URIs in v1.7+ apps use a centralized proxy format:

Copy
https://webhooks.gadget-services.net/shopify/v1/{optional-trigger-key}?domain={your-app-env-domain}

• For model webhooks without a filter or include_fields, the {optional-trigger-key} is omitted. These topics are grouped into the default [[webhooks.subscriptions]] entry that includes all standard data model topics.
• For model webhooks with a filter or include_fields, and for global action webhooks, the {optional-trigger-key} matches the triggerKey defined in the action code. These get their own separate [[webhooks.subscriptions]] entry.

Here is an example of a 1.7+ TOML file with webhook subscriptions:

example shopify.app.toml with webhook subscriptions
toml
Copy
[webhooks]
api_version = "2024-10"

# Model webhook subscriptions (auto-generated for enabled models)
[[webhooks.subscriptions]]
topics = ["products/create", "products/update", "products/delete"]
uri = "https://webhooks.gadget-services.net/shopify/v1?domain=my-app--development.gadget.app"

# Model action webhook with filter and include_fields (linked via triggerKey)
[[webhooks.subscriptions]]
topics = ["products/update"]
filter = "vendor:Nike"
include_fields = ["id", "title", "vendor", "updated_at"]
uri = "https://webhooks.gadget-services.net/shopify/v1/shopifyProduct-update?domain=my-app--development.gadget.app"

# Global action webhook subscription (linked via triggerKey)
[[webhooks.subscriptions]]
topics = ["orders/create"]
uri = "https://webhooks.gadget-services.net/shopify/v1/myGlobalAction?domain=my-app--development.gadget.app"

# Compliance webhook subscription
[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "https://webhooks.gadget-services.net/shopify/v1?domain=my-app--development.gadget.app"

You can also manually edit the [[webhooks.subscriptions]] entries in the TOML file.

Changes made in the TOML file will be reflected in the Gadget editor on sync.

For more details on how webhook triggers work in v1.7+ apps, see the triggers guide and the working with Shopify webhooks guide.

Webhook filtering 

In framework v1.7+, webhook filters and include fields are configured directly in the TOML [[webhooks.subscriptions]] entries using the filter and include_fields fields. Gadget writes these automatically when you configure them through the editor.

shopify.app.toml
toml
Copy
# Trigger key: shopifyProduct-update
[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "https://webhooks.gadget-services.net/shopify/v1/shopifyProduct-update?domain=my-app--development.gadget.app"
filter = "vendor:Nike"
include_fields = ["id", "title", "vendor", "updated_at"]

Multiple development environments 

You will have a different primary TOML file for each environment.

This means that if you are working on an app as a team, you may have multiple TOML files in your project. Each environment has its own primary TOML file, and you will also have a separate TOML file for your production app.

You will usually have a separate primary TOML file for each development environment in your project.

For example, you may have the following primary TOML files in a single app:

example of toml files in a single app
Copy
shopify.app.toml // for your production environment's Shopify app

shopify.app.development.toml // for your development environment
shopify.app.carl-dev.toml // for a carl-dev development environment

In this setup, shopify.app.toml for production and shopify.app.<environment>.toml for each development environment are the primary TOML files.

To switch between environment configurations while building, you can use the Shopify CLI's shopify app config use command:

terminal
Copy
// example of switching to a development environment
yarn shopify:config:use:development

To see the current configuration, you can use the Shopify CLI's shopify app info command.

get current configuration
Copy
yarn shopify:info

Secondary TOML files 

Secondary TOML files are additional shopify.app.*.toml files for the same environment that connect extra Shopify apps.

Secondary TOML files are supported, but they are not the default workflow. Gadget manages the primary TOML file for each environment. You are responsible for keeping any secondary TOML files in sync and deploying them separately.

This also applies to production. If you add multiple Shopify app configurations to production, Gadget will not automatically create or manage those extra TOML files for you. You need to create and manage them manually.

Pre-framework v1.7 behavior 

If your app uses a framework version earlier than v1.7, the TOML workflow differs from the default behavior described above.

TOML file management 

Only newer Gadget apps automatically receive managed TOML files. Older Shopify apps may require you to create and maintain TOML files manually.

Shopify-managed installs 

Shopify-managed installs only applied to pre-framework v1.7 apps. If your app still relies on that setup, upgrade to framework v1.7+ instead of adding new Shopify-managed install configuration to an older TOML workflow.

If you still need the older setup while migrating, see Shopify App OAuth.

Webhook subscriptions 

Gadget manages Shopify webhook subscriptions automatically. You do not need to add or edit [[webhooks.subscriptions]] entries in the shopify.app.toml file.

Webhook filtering 

Webhook filters and include fields are configured in action code using the shopifyFilter and includeFields options, not in the shopify.app.toml file.

For full details on filtering Shopify webhooks, see the webhook filtering guide.