Active Subscription Not Updated

Shopify App Store
1

Our apps are currently still using the legacy Billing API. We are planning to migrate, but for now we’re waiting and closely following the related discussions and challenges around the migration process.

One of the stores using our app recently contacted us requesting a refund for an active annual subscription. Based on our previous experience, when we issue a refund and the merchant later reinstalls the app, Shopify may process another refund automatically. To avoid this, we decided that the merchant should reinstall the app and select a monthly plan instead. To our surprise, the merchant did not receive a refund for the annual subscription.

We are aware of the new API that provides the current subscription status:

To investigate, we queried the subscription data for this shop using our app:

{
  "appId": "gid://shopify/App/43187142657",
  "shopId": "gid://shopify/Shop/78932181304"
}

And received the following response:

{
  "data": {
    "activeSubscription": {
      "shop": {
        "id": "gid://shopify/Shop/78932181304"
      },
      "cancelAtEndOfCycle": true,
      "trialEndsAt": "2025-04-10T21:06:26Z",
      "currentBillingCycle": {
        "startTime": "2026-04-10T21:06:26Z",
        "endTime": "2027-04-10T21:06:26Z"
      },
      "items": [
        {
          "handle": null,
          "description": "",
          "price": {
            "__typename": "FlatRatePrice",
            "active": false,
            "currency": "USD",
            "amount": "69.99"
          },
          "discount": null,
          "usage": null
        }
      ],
      "pendingUpdate": null,
      "legacySubscriptionId": "gid://shopify/AppSubscription/34630533432",
      "billingPeriod": "ANNUAL"
    }
  }
}

However, this does not appear to be correct, because the merchant has already activated a monthly subscription:

Screenshot 2026-06-01 at 16.44.24
Screenshot 2026-06-01 at 16.44.241244×1644 338 KB

We’re trying to understand why there is a discrepancy between the API response and the actual subscription selected by the merchant. In our appSubscriptionCreate mutation, we use the default value for replacementBehavior, which is STANDARD. Could this be the cause of the issue?

Separately, we also believe that when an app is uninstalled and the subscription is cancelled, the subscription should be terminated immediately rather than remaining active until the end of the billing cycle.

2

Hey @sebastian.pisula, replacementBehavior: STANDARD is likely part of what you’re seeing here.

For appSubscriptionCreate, STANDARD usually replaces the current subscription immediately, but annual-to-monthly changes in the same currency are one of the cases where we defer the replacement until the start of the next billing cycle.

For the other point, uninstalling an app cancels future billing, but it doesn’t automatically apply a credit for the unused remainder of the current billing period. Merchants can reinstall and continue using the app for the remainder of that paid period.

Before deciding whether any billing adjustment is needed, I’d account for our proration and deferral behavior where plan changes can be prorated, and annual-to-30-day changes are deferred until the annual cycle completes. If you need the annual subscription to be replaced immediately, use replacementBehavior: APPLY_IMMEDIATELY when creating the new subscription.

When the goal is to offset a pending/upcoming charge, that would be handled separately through an app credit/reversal flow.

3

@KyleG-Shopify Doesn’t this mean that the pendingUpdate field should be populated in some way? At the moment, it has a value of null, even though the subscription change has been deferred until the next billing cycle.

4

Not necessarily. The app subscription state and app billing timing are related, but not always the same thing.

I went into this in more detail in this earlier thread, but the TLDR; is a merchant can only have one active app subscription at a time, so the app subscription APIs generally reflect the accepted/current subscription state. The replacement behavior is about when the billing change takes effect, which can be deferred separately from the subscription state.