Subscription cancellation scenarios and lack of documentation

[ProveSource]

Shopify billing API guides offer no guidance on how to monitor cancelled subscriptions and what's the best approach.

At first, we opted to the "app/uninstall" webhook initially and thought this would be a solution.

We later found out that RecurringCharges will be frozen if a user "frozen" his store which can be found using the "shop/update" webhook and checking the `plan_name` in the payload.

Later we found out that `plan_name` is not documented fully and can have many values that symbolize a closed store, e.g.

• frozen
• cancelled
• dormant
• fraudulent

And we probably missed a few more.

We also found the "app_subscription/update" webhhook but there is no documentation for this one whatsoever and it seems it's not implemented yet.

Eventually, it seems the only option right now to identify if a RecurringApplicationCharge is cancelled with 100% certainty is by polling the API with a CRON which is not very efficient or simple.

Why is it so complicated and not documented?

So many documentation pages:

• https://shopify.dev/tutorials/manage-subscriptions-with-billing-api
• https://shopify.dev/tutorials/add-billing-to-your-app
• https://shopify.dev/docs/admin-api/rest/reference/billing/recurringapplicationcharge

but none of those pages have any mention of dealing with cancellation.

Shopify team, please update your documentation.

[ProveSource]

Bump

[SBD_]

Hey @ProveSource,

shop/update will fire when a shop property is updated (including plan changes).

[ProveSource]

@SBD_ 

Thanks, but as mentioned there are many undocumented possible values for Shop's plan:

frozen
cancelled
dormant
fraudulent

And the shop/update webhook does not tell us if the merchant will be billed for your app in the future or not.

Unless you can specify how to do it better?

This is exactly what the post is about - there's no documentation about how to handle subscription cancellations other than manual cancellations or uninstall of the app.

[SBD_]

Valid feedback. Thanks, I'll pass this on.

[Brian29]

I agree with poster. It is extremely difficult on our end to sync up reliably with who actually has an active shopify subscription in a bulk fashion. It does seem the only "reliable" way is to iterate over all users on our end and query the shopify api billing system. Curious as to how anyone else is managing this on their end.

[ProveSource]

We've created a daily polling mechanism to check the billing API response for each and every user.

Moreover, the Shopify billing API will report a user's plan as valid even though his store is no longer active.

For example, a shop is to be billed on April 15th, but the shop is frozen/cancelled.

The billing API will still report the subscription charge as active and billed on April 15th.

The billing API will only report the billing is inactive on April 15th.

[edwardupton]

+1 for clarifying the states that `plan_name` can return

[Natashz]

Strongly agree with the poster. We spent SO much time, trying to understand all the scenarios.

After doing that we subscribed to the appSubscriptionUpdate webhook, however, it seems we're not getting ANY of the expected notifications there when the shop updated the plan.

There is no documentation as to when this will fire, how the data is expected to look like, or anything at all basically. This is very frustrating... 

This is what we came up with:

• Canceled - The shop is closed permanently. Recurring application charges are removed. Partners must create new recurring application charges if the store re-opens.
• Frozen - The shop is paused temporarily. Recurring application charges become inactive but remain in the store. The recurring application charges will resume after the store is unfrozen.
• Dormant - Open with no orders, usually temporarily. Recurring application charges stay active and are charged normally
• Fraudulent - Shop has been closed (can be permanent or temporary). Probably like “canceled”.

[1080]

@Natashz   can you please the status code code reference block for the same 

[EugeneKim]

Shopify staff can we please get an update on this? Clarification on plan_name has been asked again and again without sufficient responses from staff. This isn't something that partners can figure out on our own and this is internal knowledge that isn't publicly documented.

I just asked a related question here.

This post also asked for a full list of plan_name values. No response from shopify staff and it was asked four years ago. Other Shopify partners tried their best to crowd source the various values but without context as to what plan_name can mean, it doesn't really help us.

Shopify Staff, please help us write better software for merchants. Tell us something, even if it's just that there are no plans to document plan_name at this time. It would be disappointing but still less frustrating than the silence.

[nikola_seo]

2024, no improvements 😕

[ShopifyDevSup]

Hey @nikola_seo , 

Thanks for the repost here. I know this is an old thread, but I'm happy to discuss. 

As it relates to app billing, can you share the reason the plan is needed? I know a lot has been discussed already, but the reason I'm asking is because when a shop is changed to any of the inactive states, unless the app is uninstalled; if the store plan is re-activated, the current app subscription will resume until the merchant uninstalls the app. 

The charge details should be sufficient to understand any action your app needs to take based on the app subscription (cancelled, frozen, etc) https://shopify.dev/docs/apps/launch/billing/view-charges-earnings#subscription-charge-details 

This should also be returned in the APP_SUBSCRIPTIONS_UPDATE webhook, as explained here: https://shopify.dev/docs/apps/launch/billing/subscription-billing/create-time-based-subscriptions#st... 

Hopefully that helps give some clarity around the current settings. I'm happy to continue to pass feedback on to our billing team! 

- Kyle G.