Inconsistent Behavior for replacementBehavior=APPLY_ON_NEXT_BILLING_CYCLE in appSubscriptionCreate Mutation

GraphQL Admin API Troubleshooting
,
1

Hello Shopify Dev Team,

I am reporting an issue regarding the appSubscriptionCreate GraphQL mutation, specifically when using the parameter replacementBehavior: APPLY_ON_NEXT_BILLING_CYCLE.

Problem Description

During the subscription upgrade/downgrade flow:

  1. When creating a new app subscription with replacementBehavior set to APPLY_ON_NEXT_BILLING_CYCLE, the billing page correctly displays a message to the merchant indicating that the change will take effect at the end of the current billing cycle.

  2. However, immediately after the merchant approves the change, our application receives two webhook payloads from the app_subscriptions/update endpoint:

    • One payload indicates the cancellation of the current active subscription.

    • Another payload indicates the activation of the new subscription.

This observed behavior—where the old subscription is canceled and a new one is activated immediately—contradicts the expectation set by the APPLY_ON_NEXT_BILLING_CYCLE option, which should delay the application of the new plan until the next billing cycle.

Expected Behavior

When replacementBehavior: APPLY_ON_NEXT_BILLING_CYCLE is used, the existing subscription should remain active until the end of its current billing period. The new subscription plan should only become active at the start of the next billing cycle. The immediate cancellation of the old subscription and activation of the new one is unexpected.

Steps to Reproduce

  1. Have an active recurring application charge for a shop.

  2. Call the appSubscriptionCreate mutation with a new plan and replacementBehavior: APPLY_ON_NEXT_BILLING_CYCLE.

  3. Direct the merchant to the generated confirmationUrl.

  4. As the merchant, approve the change on the billing page (which correctly states the change will apply later).

  5. Observe the webhooks sent to the app_subscriptions/update endpoint, which show immediate cancellation of the old subscription and activation of the new one.

Additional Context

This behavior causes confusion in application logic that relies on the webhook data to track a shop’s active subscription status. The immediate activation also seems inconsistent with the prorated billing model typically associated with plan changes applied in the next cycle .

Could you please clarify if this is the intended behavior or confirm if it is a bug? If it is a bug, we request a fix to align the system’s action with the parameter’s description.

Thank you for your time and assistance.

1 Like
2

Hey @TingTing_Xia,

You are seeing the expected behavior here! Currently it’s only possible for merchants to have one active app subscription at a time, so when you use APPLY_ON_NEXT_BILLING_CYCLE, the old subscription is marked as cancelled as the merchant has accepted the new one. The replacement behavior is specifically about billing timing, not the subscription management itself.

This means your app gets to control the timing of when features are actually enabled or disabled based on the billing cycle.

3

Hey @TingTing_Xia, does the above help better understand the expected behaviour?