Gadget framework
Changelog
Glossary
FAQ

Migrating your app to framework v1.7.0 

Gadget framework version 1.7.0 introduces a TOML-based Shopify configuration model.

Your Shopify connection settings, OAuth scopes, and webhook subscriptions are now managed through TOML files instead of action code and editor settings. This guide covers the breaking changes and migration steps.

The 1.7 migration involves many file changes across your app. Back up your app using source control before starting the migration. Once upgraded, you cannot downgrade back to 1.6 via the editor. If the migration causes issues that source control cannot resolve, contact us on our Discord. We create an internal backup before running the migration and can help restore your app.

Shopify CLI authentication required 

Upgrading to v1.7 requires authenticating with Shopify Partners to enable the new TOML-based connection.

When you upgrade, Gadget will prompt you to authenticate using the Shopify CLI. This links your Gadget app to your Shopify Partner account and allows Gadget to manage your TOML configuration.

You can switch to a different Shopify Partner account during connection creation if needed.

TOML-based Shopify configuration 

Each environment now has a primary TOML file that serves as the source of truth for that environment's Shopify app configuration:

  • shopify.app.toml for your production environment
  • shopify.app.{environment-name}.toml for non-production environments, such as shopify.app.development.toml

Client ID, API version, URLs, and app metadata are all defined in the primary TOML file. For more details on managing TOML files, see the Shopify App TOML guide.

OAuth scopes moved to TOML 

OAuth scopes are now defined under [access_scopes] in your shopify.app.toml file instead of the scopes array in settings.gadget.ts.

In v1.7+ apps, scopes are defined in your TOML file. 

shopify.app.toml (1.7+)
toml
[access_scopes]
scopes = "read_products,write_products,read_orders"

Pre-framework v1.7

Scopes were configured in settings.gadget.ts:

settings.gadget.ts (pre-1.7)
TypeScript
export const settings: Config = { plugins: { connections: { shopify: { scopes: ["read_products", "write_products", "read_orders"], }, }, }, };
export const settings: Config = { plugins: { connections: { shopify: { scopes: ["read_products", "write_products", "read_orders"], }, }, }, };

Gadget automatically migrates your existing scopes to the TOML file when you upgrade to 1.7. You do not need to manually copy them.

Global action Shopify webhook topics moved to TOML 

Webhook topics for global actions with Shopify triggers are now defined as [[webhooks.subscriptions]] entries in your TOML file instead of inline in action code.

Action files reference their TOML subscription using a triggerKey.

Gadget automatically migrates your existing global action webhook topics to the TOML file when you upgrade to 1.7. The webhooks array in your action code is replaced with a triggerKey, and a matching [[webhooks.subscriptions]] entry is created in your TOML file.

In v1.7+ apps, global action webhook topics are referenced from action code using a triggerKey, with the subscription stored in TOML.

api/actions/productUpdates.ts (1.7+)
TypeScript
export const options: ActionOptions = { triggers: { shopify: { triggerKey: "productUpdates", }, }, };
export const options: ActionOptions = { triggers: { shopify: { triggerKey: "productUpdates", }, }, };
shopify.app.toml
toml
[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "https://webhooks.gadget-services.net/shopify/v1/productUpdates?domain=my-app--development.gadget.app"

Pre-framework v1.7

api/actions/productUpdates.ts (pre-1.7)
TypeScript
export const options: ActionOptions = { triggers: { shopify: { webhooks: ["products/update"], }, }, };
export const options: ActionOptions = { triggers: { shopify: { webhooks: ["products/update"], }, }, };

Webhook filters and includeFields are also configured in the TOML file for v1.7+ apps.

See the webhook triggers guide and the working with Shopify webhooks guide for full details.

Model actions that do not use filter or include_fields do not need a triggerKey. Their webhook topics remain in the default [[webhooks.subscriptions]] block alongside other standard topics. Only model actions that have a filter or include_fields configured get their own [[webhooks.subscriptions]] block and a corresponding triggerKey in the action code.

Webhook registrations change on migration 

When you upgrade to v1.7, how your webhook subscriptions are managed changes fundamentally.

In pre-v1.7 apps, all webhooks are registered per-shop through the Shopify GraphQL API as shop-specific subscriptions. In v1.7+ apps, most webhooks become app-managed subscriptions defined in your TOML file.

See the Shopify documentation on app-specific vs shop-specific subscriptions for more details on the difference between these subscription types.

Webhook callback URLs have changed 

In v1.7+ apps, webhook callback URLs use a dedicated webhook ingress domain instead of your app's domain.

No action is required for TOML-managed models because Gadget generates the new URLs automatically when you run shopify app deploy. For metafield models that use shop-specific registrations, re-registering webhooks through the Installs page updates the callback URLs.

Pre-1.71.7+
DomainYour app domainDedicated webhook ingress
Formathttps://{app}.gadget.app/api/webhooks/shopifyhttps://webhooks.gadget-services.net/shopify/v1/{triggerKey}?domain={app}.gadget.app

Development environment: all webhooks are unregistered 

When you migrate your development environment to 1.7, Gadget unregisters all existing per-shop webhook subscriptions from your development shops. This is necessary because your webhooks are moving from per-shop registrations to app-managed TOML subscriptions.

After the migration completes, you must take two steps to restore your webhook subscriptions:

Step 1: Run shopify app deploy to activate TOML-managed webhooks

Run shopify app deploy using the Shopify CLI to register the app-managed webhook subscriptions defined in your TOML file:

terminal
shopify app deploy

After migrating to 1.7, Gadget will open the terminal and prompt you to run shopify app deploy for your development environment. You must complete this step to activate your TOML-managed webhook subscriptions. Without it, your app will not receive webhook events from Shopify in development. This step is only required for your development environment. For production, Gadget automatically runs shopify app deploy during deployment.

Step 2: Re-register shop-specific webhooks for metafield models

Models that use Shopify metafield namespaces are not managed through the TOML file.

Their webhooks remain per-shop and are registered using the Shopify GraphQL API. After migration, you must manually re-register these webhooks for each existing shop:

  1. Navigate to the Installs page for your Shopify connection in the Gadget editor
  2. For each installed shop, open the More Actions menu
  3. Click Register shop specific webhooks

This registers the metafield namespace webhooks using the new 1.7+ callback URL. New shop installations will register these webhooks automatically.

If your app does not use metafield namespaces on any Shopify models, you can skip Step 2. You only need to re-register shop-specific webhooks for models that have metafield fields enabled.

Production environment: automatic cleanup on deploy 

Gadget does not modify any existing webhook registrations on your production shops during migration. Your production webhooks continue to work as before until you deploy.

When you deploy to production, Gadget automatically:

  1. Runs shopify app deploy to register your TOML-managed webhook subscriptions
  2. Unregisters old per-shop webhook subscriptions for topics that are now TOML-managed, preventing duplicate deliveries
  3. Updates per-shop webhook subscriptions for metafield models to use the new 1.7+ callback URL

Gadget only cleans up production webhooks after a successful shopify app deploy. If the deploy fails, your existing production webhooks are left untouched.

Shop-specific webhook registrations for metafield models 

Models that use Shopify metafield namespaces are an exception to the app-managed webhook model.

These webhooks remain shop-specific because they require per-shop namespace configuration and are registered using the Shopify GraphQL API.

In v1.7+ apps, shop-specific registrations are tracked in the new shopSpecificRegistration field on the shopifyShop model. This field replaces the deprecated registeredWebhooks field for this purpose.

Enabled Shopify models are now computed automatically 

In pre-v1.7 apps, the list of enabled Shopify models was stored as an explicit setting in your connection configuration.

In v1.7+ apps, there is no stored list. Instead, which Shopify models are enabled is computed automatically based on two factors:

  1. The model exists in your current environment: Shopify data models are present in your app's file tree
  2. The required OAuth scopes are satisfied: the scopes needed for the model are present in [access_scopes] in your TOML file

A Shopify model is considered enabled when both conditions are met. Child models like shopifyProductVariant also require their parent model like shopifyProduct to be present.

During migration, models may become enabled that were not enabled before.

If a Shopify data model exists in your current environment and its required scopes are present in [access_scopes], it will become enabled even if it was not enabled in your pre-1.7 connection config. This can result in new webhook subscriptions being registered and new data being synced for models you were not previously using.

Models that were enabled before the migration will not be removed. Gadget ensures the necessary scopes are added to the TOML file during migration to preserve your existing configuration.

The shopifyShop and shopifySync models are always included by default.

Before upgrading to 1.7, review the Shopify data models in your current environment. Remove any model files you do not want enabled, because any model with matching scopes will be automatically enabled after migration.

For example, after migrating to 1.7, the shopifyProduct model is considered enabled because the shopifyProduct data model exists in your current environment and the read_products scope is present in [access_scopes]:

shopify.app.toml (after migration)
toml
[access_scopes]
scopes = "read_products"

When you enable or disable models through the Gadget editor, Gadget automatically updates both the scopes and webhook subscriptions in your TOML file to match.

Some individual model fields also require specific scopes beyond the base model scopes. If a required scope for a field is not present in [access_scopes], that field will not be included in your model even if the model itself is enabled.

shopSpecificWebhooks field added to the shop model 

A new shopSpecificWebhooks field has been added to the shopifyShop model. This field stores resources that use metafield-based webhook registrations, which are registered per-shop via the Shopify GraphQL API rather than through the TOML file.

Deprecated fields on the shopifyShop model 

registeredWebhooks 

The registeredWebhooks field is no longer authoritative in v1.7+ apps. Webhook registration state is now derived from the [[webhooks.subscriptions]] entries in your primary TOML configuration. The field still exists on the model but should not be relied on for webhook state.

If you have logic that reads registeredWebhooks to make decisions in your action code, you should update that logic to reference your TOML configuration instead.

disabledWebhooks no longer affects webhook registration 

In pre-v1.7 apps, the disabledWebhooks field on the shopifyShop model could be used to prevent certain webhooks from being registered for a shop.

In v1.7+ apps, this field no longer affects webhook registration because webhook subscriptions are now managed through the TOML file at the app level, not per-shop.

If you were using disabledWebhooks to control webhook processing, you will need to implement alternative logic in your action code to skip processing for specific shops or models.

Secondary Shopify apps require manual management 

In pre-v1.7 apps, Gadget automatically managed secondary Shopify app connections.

In v1.7+ apps, secondary apps become separate secondary TOML files that you must manage yourself.

This means:

  • You are responsible for keeping your secondary TOML files in sync with your primary TOML configuration
  • You must run shopify app deploy separately for each secondary TOML file. Gadget only auto-deploys your primary TOML during production deployments.

For more details on primary vs secondary TOML files, see the Shopify App TOML guide.

Shopify App Details page removed 

The standalone Shopify App Details page in the Gadget editor has been removed. App metadata such as app name, URLs, and configuration are now managed exclusively through your TOML files and the Shopify connection settings page.

If you have issues after upgrading to v1.7.0, reach out on our Discord.

Was this page helpful?