Process for an app theme extension with subscription model and webhooks

Shopify Apps
, ,

Topic summary

Managing a theme app extension’s visibility based on subscription status using Shopify metafields and webhooks.

  • Approach: Set an AppInstallation metafield (namespace: applicationInstallation, key: paid, boolean) via GraphQL, then gate the block with schema available_if = app.metafields.applicationInstallation.paid.
  • Optimization: Use webhooks to avoid per-request server checks. Implement a webhook on APP_SUBSCRIPTIONS_UPDATE; when payload status (AppSubscriptionStatus) is ACTIVE, update the metafield to enable the block.

Key answers provided:

  • Security: Using app-owned metafields is acceptable if access is controlled via your app’s auth; ensure secure handlers and validation.
  • Events: webhookSubscriptionCreate assumed to fire on subscription creation/payment; webhookSubscriptionUpdate to reflect status changes (e.g., failed payments, cancellations). Consider handling additional events for upgrades/downgrades.

Recent update: OP tested successfully—APP_SUBSCRIPTIONS_UPDATE sets metafield to enable the block when status is ACTIVE.

Open questions/uncertainties:

  • Whether these webhooks are strictly for app billing vs store plan subscription wasn’t definitively clarified.
  • Who can modify the app-data metafield: OP assumes only the app (via OAuth/app token) can change AppInstallation metafields; not explicitly confirmed.
  • A challenge raised: APP_SUBSCRIPTIONS_UPDATE may not fire on initial successful billing, leaving unclear when to set the metafield first. Discussion remains open.
Summarized with AI on December 28. AI used: gpt-5.
1

Hi there, I have created an app and now I am checking how can I deploy this and I have a few questions about the process as this is my first app and I am totally new on shopify.

So, after I finished my app and selected a subscription model, I had noticed that app shows up on admin after install but it keeps showing before the user pay for the app… I tried to find a few solutions and the way I am thinking in do this is:

1 - Creating a app-data metafield using this mutation:

mutation CreateAppDataMetafield($metafieldsSetInput: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafieldsSetInput) {
    metafields {
      id
      namespace
      key
    }
    userErrors {
      field
      message
    }
  }
}

{
  "metafieldsSetInput": [
    {
      "namespace": "applicationInstallation",
      "key": "paid",
      "type": "boolean",
      "value": "true",
      "ownerId": "gid://shopify/AppInstallation/XXXXXXXXXXXX <- got it from currentAppInstallation"
    }
  ]
}

Now I can use on my liquid file:

{% schema %}
   "available_if": "{{ app.metafields.applicationInstallation.paid }}",
{% endschema %}

So this way I can enable/disable the content to be displayed on frontend.

Now I needed a way to set this in a way that will consume less server, so instead check my server for each request, I am thinking in use webhooks for check the payment/subscription.

I have found these ones:

webhookSubscriptionUpdate,

webhookSubscriptionCreate

So my questions are:

1 - Managing the app view via metafields like app.metafields.applicationInstallation.paid is safe? Does someone can set this via graphql beside me?

2 - If I create a custom webhookSubscriptionCreate I should be able to get the data after a merchange pays the subscription?

3 - If the customer doesn’t pay the subscription for some reason, like not having money in the credit card, I should get an update from webhookSubscriptionUpdate ?

4 - It’s safe assume that I can use only these 2 webhooks for managing this enable/disable feature for merchants?

Thank you.

1 Like
2

@lima195

Your approach to using metafields and webhooks to manage the app view and subscription status on Shopify is a good start. Let’s address your questions:

  1. Managing app view via metafields (app.metafields.applicationInstallation.paid):
  • Using metafields to control the visibility of your app’s content is generally safe. However, it’s crucial to ensure proper validation and authentication mechanisms to prevent unauthorized access or manipulation. As long as you have control over who can modify these metafields via your app’s logic and authentication mechanisms, it should be secure.
  1. Creating a custom webhookSubscriptionCreate:
  • When a merchant pays for a subscription, the webhookSubscriptionCreate event will trigger if your app is set up to receive this event. You should receive data related to the newly created subscription, allowing you to update the metafields or perform other necessary actions based on the payment status.
  1. Getting updates on failed subscription payments (webhookSubscriptionUpdate):
  • Yes, the webhookSubscriptionUpdate event can provide information on changes to subscription status, including failed payments or cancellations. You can use this event to manage the state of the subscription within your app and take appropriate actions, such as disabling features or prompting the merchant to update payment information.
  1. Using webhooks for managing enable/disable features:
  • While webhookSubscriptionCreate and webhookSubscriptionUpdate are essential for managing subscription-related events, there might be other events or situations (like successful payments, cancellations, or upgrades) that you might want to handle. Consider additional webhooks or a combination of Shopify APIs to cover a broader range of scenarios that impact your app’s functionality.

Ensure that your webhook handlers are implemented securely and can handle various scenarios, including retries, failures, and edge cases like network issues or delayed events.

Finally, consider the possibility of testing these scenarios in a development or staging environment to ensure that your app responds correctly to different subscription-related events before deploying changes to production.

1 Like
3

Thank you for cover all points, I just wanted to check if these webhooks are related to the app payment subscription itself or if it could be related to the customer store subscription.

For the metafield, only the app owner has the credentials to change it? Like having the oauth (app key and app private key), so only the app owner has access to this auth and app instalation id? If so, should be the only one able to change the app-data metafield I guess.

4

So, I did a full test here and this approach works…
I had to create a webhook (webhookSubscriptionCreate) for the topic “APP_SUBSCRIPTIONS_UPDATE” there I have pointed a url to my server, in this server I am just checking the payload, there is a status on it (AppSubscriptionStatus (shopify.dev)) and if it’s ACTIVE I send a request to CreateAppDataMetafield creating/updating the value to enable/disable the theme extension block.
I hope this can help more people…

5

Hey Lima, Thanks for sharing your experience.

Just wondering, as far as I undestood the “APP_SUBSCRIPTIONS_UPDATE” wont send a webhook if the billing was successfull, it only sends out a webhook if the current subscription gets either canceled or changed.

So at which point do you create the app data metafield