Orders/paid webhook declared in shopify.app.toml not registering (managed installation, protected data approved)

Shopify App Store
1

Hello Shopify team,

I’m developing an app for Chilean tax invoicing and I’m unable to get
the orders/paid webhook to register, despite having completed all
required configurations.

My setup

  • App using Shopify Managed Installation
  • React Router + JavaScript template
  • @shopify/shopify-app-react-router/server v13.0.0
  • API version: 2026-07
  • Scopes approved: read_products, write_products, read_orders, read_customers, write_metaobjects, write_metaobject_definitions
  • Protected customer data access: approved (Level 1 and Level 2)
  • Tested on development store: boletas-chile-app.myshopify.com

What I’ve done

  1. Declared the webhook subscription in shopify.app.toml:
[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"

  [[webhooks.subscriptions]]
  topics = [ "orders/paid" ]
  uri = "/webhooks/orders/paid"
  1. Created the webhook handler at app/routes/webhooks.orders.paid.jsx
  2. Ran shopify app deploy — completed successfully, version released
  3. Uninstalled and reinstalled the app on the development store
  4. Verified orders/paid is an approved topic under my protected
    customer data configuration

The problem

  • Test orders don’t trigger the webhook — terminal with
    shopify app dev remains completely silent after successful checkout
  • Running shopify webhook trigger and navigating topics, I only see
    app/scopes_update and app/uninstalled — orders/paid is NOT
    in the list    , even though the other two webhooks from my toml ARE
    listed
  • Partners Dashboard doesn’t show any webhooks registered for my app

This suggests Shopify read two of the three webhook subscriptions
from my toml, but silently ignored orders/paid.

What I’ve ruled out

  • :cross_mark: Not a code issue — handler file exists and compiles cleanly
  • :cross_mark: Not a scopes issue — read_orders is approved
  • :cross_mark: Not a protected data issue — already approved for customer data
  • :cross_mark: Not a deploy issue — deploy completes with success message
  • :cross_mark: Not a reinstall issue — uninstalled/reinstalled multiple times

What I need help with

Why is orders/paid being silently ignored from my webhook
subscriptions? Is there something specific about the 2026-07 API
version or managed installation flow that requires additional
configuration for order-related webhooks?

Thank you for any guidance.

2

Hey @Franciscoaho The pattern where just orders/paid fails to register while app/uninstalled and app/scopes_update register cleanly usually points to a missing access scope in your app config. The two topics that registered don’t need any scope, but orders/paid requires read_orders, and with managed installation the scope has to be declared in the [access_scopes].scopes string in shopify.app.toml. Approving Protected Customer Data in the Partner Dashboard grants permission for the scope, but the app still has to request it in the config, otherwise managed install never includes it in the install grant.

Your toml likely needs a line similar to this one.

[access_scopes]
scopes = "read_products,write_products,read_orders,read_customers,write_metaobjects,write_metaobject_definitions"

The Subscribe to a webhook topic guide has the canonical example under “Update your access scopes”. Once that’s in place, run shopify app deploy, then reinstall the app on your dev store so the merchant re-grants the new scope. After that, shopify webhook trigger should list orders/paid and a test checkout will fire the webhook.

If read_orders is already in your [access_scopes] block, share the full toml (minus client_id) and the output of your last shopify app deploy and I’ll take another look.

3

Hi, thanks a lot for the quick response!

I confirmed that read_orders is already in my [access_scopes] block. I’ve also completed Protected Customer Data approval for Level 1 and Level 2. Below is my full shopify.app.toml (client_id redacted) and details of what I’ve already tried.

My full shopify.app.toml

client_id = “REDACTED”
name = “filu-app-2026”
application_url = “https://example.com”
embedded = true

[build]
automatically_update_urls_on_dev = true
include_config_on_deploy = 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”

[[webhooks.subscriptions]]
topics = [ “orders/paid” ]
uri = “/webhooks/orders/paid”

[access_scopes]
scopes = “read_products,write_products,read_orders,read_customers,write_metaobjects,write_metaobject_definitions”

[auth]
redirect_urls = [ “https://example.com/api/auth” ]

[product.metafields.app.demo_info]
type = “single_line_text_field”
name = “Demo Source Info”
description = “Tracks products created by the Shopify app template for development”

[product.metafields.app.demo_info.access]
admin = “merchant_read_write”

[metaobjects.app.example]
name = “Example”
description = “An example metaobject definition created by this template”

[metaobjects.app.example.access]
admin = “merchant_read_write”

[metaobjects.app.example.fields.title]
name = “Title”
type = “single_line_text_field”
required = true

[metaobjects.app.example.fields.description]
name = “Description”
type = “multi_line_text_field”

What I’ve already tried

  1. Ran shopify app deploy — output showed “success, new version released to users” (version filu-app-chile-2)
  2. Uninstalled the app from the dev store admin
  3. Reinstalled via shopify app dev + pressing ‘p’ to preview
  4. Confirmed the two system webhooks (app/uninstalled, app/scopes_update) work — they appear in the shopify webhook trigger topic list
  5. orders/paid does NOT appear in the topic list from shopify webhook trigger, only the two system webhooks do
  6. Test checkouts via bogus gateway complete successfully but the webhook endpoint never receives anything — terminal with shopify app dev remains completely silent after checkout
  7. Protected Customer Data: Level 1 and Level 2 both approved in Partner Dashboard
  8. Tried multiple uninstall/reinstall cycles with same result

Additional context

  • Using @shopify/shopify-app-react-router/server v13.0.0
  • React Router template with managed installation flow
  • Dev store: boletas-chile-app.myshopify.com
  • The handler file exists at app/routes/webhooks.orders.paid.jsx and compiles cleanly (no errors in VS Code Problems panel)
  • API version: 2026-07

Any insight would be greatly appreciated. Thanks!

5

Hi Donal,

Following up on your previous suggestion — read_orders is already
in my access_scopes, so I wanted to share more details.

The key finding: when I run shopify webhook trigger with API
version 2025-10, both app/uninstalled and app/scopes_update
appear in the topic list (the other two webhooks from my toml),
but orders/paid does NOT appear at all.

My toml webhooks block:

[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”

[[webhooks.subscriptions]]
topics = [ “orders/paid” ]
uri = “/webhooks/orders/paid”

[access_scopes]
scopes = “read_products,write_products,read_orders,
read_customers,write_metaobjects,write_metaobject_definitions”

What I have confirmed:

  • read_orders is in access_scopes
  • Protected Customer Data Level 1 and Level 2 approved
  • shopify app deploy completed successfully
  • Multiple clean uninstall and reinstall cycles
  • shopify app dev --reset tried
  • Handler file exists and compiles cleanly
  • Test checkouts complete but terminal stays silent

The system webhooks register fine. Only orders/paid is ignored.

Could the placeholder application_url in toml cause Shopify
to silently reject orders/paid during deploy? Or is there
something specific about orders/paid in managed installation
that requires additional configuration beyond read_orders
and protected data approval?

Thank you

6

Thanks for the full toml, that rules out the obvious scope and PCD angles. The toml structure is correct, read_orders is in there, and PCD approval isn’t even required on a development store, so none of those should be blocking orders/paid. The placeholder application_url isn’t the cause either, since app/uninstalled and app/scopes_update use the same base and they registered fine.

The most useful next step is to look at what the dev store actually thinks is granted and registered, rather than relying on the CLI prompt. Run this against boletas-chile-app.myshopify.com using the app’s session token (GraphiQL served by shopify app dev works):

{
  currentAppInstallation {
    accessScopes { handle }
  }
  webhookSubscriptions(first: 50) {
    nodes {
      topic
      uri
    }
  }
}

If read_orders is missing from accessScopes, the install never picked up the scope change and orders/paid won’t register. A clean reinstall usually fixes that. Fully uninstall via the dev store admin (Settings, Apps and sales channels), then run shopify app dev --reset and install through the URL the CLI prints rather than the p shortcut, watching the consent screen for read_orders.

If read_orders is present but orders/paid is missing from webhookSubscriptions, that points at something happening during deploy. Share the output of that query plus a shopify app deploy --verbose log and I’ll dig further from there.