We are experiencing an issue with subscription webhooks, specifically subscription_contracts/create, and would appreciate clarification on the expected behavior.
Environment
Summary of the issue
-
Subscription contracts are being successfully created and are visible in Admin → Subscriptions → Contracts
-
Orders are created normally and we receive:
orders/createorder_transactions/create
-
However, subscription_contracts/create webhook is not delivered when the subscription is created via checkout
What we have verified
- Webhook is correctly registered (confirmed via
GET /admin/api/2025-07/webhooks.json)
- Topic is listed as
subscription_contracts/create
- Endpoint is reachable and HTTPS
- Other orders webhooks are delivered successfully:
- App has the required scopes (
write_own_subscription_contracts, read_own_subscription_contracts)
- The issue occurs while using Shopify Payments in test mode
Example behavior
- Customer completes checkout for a subscription product
- Order is created and order-related webhooks fire as expected
- Subscription contract appears in Admin
- No
subscription_contracts/create webhook is received
Questions
-
Is the absence of the subscription_contracts/create webhook for checkout-created subscriptions expected behavior, particularly when using Shopify Payments in test mode?
-
If this is expected:
- What is Shopify’s recommended approach to reliably detect newly created subscription contracts?
- Should apps rely on
orders/create combined with a GraphQL lookup of subscription contracts?
-
If this is not expected:
- re there known limitations, delays, or conditions under which this webhook is intentionally not fired?
1 Like
Hey @Gaurav_Dhandre, thanks for the details of the troubleshooting you have already completed.
I would expect the webhooks to be delivered here.
Can you share how you subscribed to the webhook? Did you do so through the API or the app configuration file?
Can you also try a query from the app that is subscribed to the webhook and query the subscription contract directly? This is to ensure that your app is able to receive the subscription contract data.
We subscribed to the subscription_contracts/create webhook via the Admin REST API (not through the app configuration file). We’ve verified the subscription using GET /admin/api/2025-07/webhooks.json, and the topic is correctly registered and active.
Additionally, we queried the subscription contract directly using the GraphQL Admin API from the same app that is subscribed to the webhook, but it returns empty records, even though the subscription is clearly visible in the Order, Customer, and Shopify Subscriptions sections in the Admin.
Please find the attached screenshots for reference.
Following up on the subscription contracts issue we discussed earlier.
This behavior is consistent when the subscription is created via checkout using Shopify Payments in test mode.
Looking forward to your guidance on the recommended way to reliably detect newly created subscription contracts.
Thanks
Gaurav
Hey @Gaurav_Dhandre,
Based on the Subscriptions section visible in your admin sidebar, it looks like you might be using the Shopify Subscriptions app (or another third-party subscription app) to handle the actual subscription creation at checkout. Can you confirm?
The reason I ask is the _own_ in your scopes (read_own_subscription_contracts, write_own_subscription_contracts) means your app can only access contracts that your app created and manages. This applies to both API queries and webhook delivery. If a different app is creating the contracts at checkout, your app won’t receive the subscription_contracts/create webhook for those, and they won’t appear in your GraphQL queries. This is by design where each subscription app owns and manages only its own contracts, and there isn’t a scope that grants access to contracts created by other apps.
If you can confirm which app is handling the subscription creation that will help clarify whether this is the expected behavior you’re seeing.
Thanks for the clarification — that makes sense.
Yes, the subscriptions are being created at checkout using the Shopify Subscriptions app (not by our app). Our app is currently only consuming order and subscription-related data post-checkout and does not create or manage the subscription contracts itself.
Given this, we understand now that because our app only has the read_own_subscription_contracts / write_own_subscription_contracts scopes, it can only access subscription contracts that were created and managed by our app. Since the contracts are owned by the Shopify Subscriptions app, it’s expected that:
Thanks for pointing this out — this explains the behavior we’re seeing.
To confirm next steps: for apps that do not own the subscription contracts, is the recommended approach to rely on orders/create (and related order webhooks) to detect subscription purchases, without direct access to the underlying subscription contract?
Appreciate your help in clarifying this.
Hey @Gaurav_Dhandre, orders/create is the right approach. One way to identify these orders is to Check the source_name field in the order payload. Subscription orders may have something like "subscription_contract". Best to test on your own store to confirm how it looks with your current set up.
If you need to query for additional details, the sellingPlan field on line items has additional info.
Thanks for the clarification — that makes sense.
We’ll proceed with using the orders/create webhook and identify subscription-related orders by inspecting the source_name field in the order payload. We’ll also review the sellingPlan field on line items to extract any additional subscription details as needed.
We’ll validate this behavior in our own test store to confirm how it appears with our current setup.
Appreciate your guidance on this.
