App Usage Charge balance used issue?

Hi,

We are noticing an issue on Usage charge as described bellow:

  • Store a.myshopify.com subscribe to our paid plan, the plan mixed between fixed monthly subscription and usage based. In this example it is app Growth plan: $99/month and usage based with capped amount: $495/month

  • Store a.myshopify.com continue to use for some days and the usage charge updated to $495 reach to the capped limit and then the merchant decided to upgrade app plan to Pro which has higher capped limit and more app features.
    => Store a.myshopify.com upgrade app plan to Professional: $399/month and usage based with capped amount: $875/month

However after upgrading to Pro plan with new capped amount for usage based successfully, the data show on Shopify subscription setting of the merchant does not reset to 0, instead it still show the old balance used: capped amount $495(taken from old subscription)

Use GraphQL to query the new Subscription to check the data with following code:

{
   node(id: "gid://shopify/AppSubscription/123123123") {
       ...on AppSubscription {
           id
           lineItems {
               id
               plan {
                   pricingDetails {
                       __typename
                       ...on AppUsagePricing {
                           cappedAmount {
                               amount
                               currencyCode
                           }
                           balanceUsed {
                               amount
                               currencyCode
                           }
                           interval
                           terms
                       }
                   }
               }
               usageRecords(first: 250) {
                   edges {
                       node {
                           id
                           createdAt
                           description
                           price {
                               amount
                           }
                       }
                   }
                   pageInfo {
                       hasNextPage
                       endCursor
                   }
               }
           }
       }
   }
}

Response is:

{
   "data": {
       "node": {
           "id": "gid://shopify/AppSubscription/123123123",
           "lineItems": [
               {
                   "id": "gid://shopify/AppSubscriptionLineItem/123123123?v=1&index=0",
                   "plan": {
                       "pricingDetails": {
                           "__typename": "AppRecurringPricing"
                       }
                   },
                   "usageRecords": {
                       "edges": [],
                       "pageInfo": {
                           "hasNextPage": false,
                           "endCursor": null
                       }
                   }
               },
               {
                   "id": "gid://shopify/AppSubscriptionLineItem/123123123?v=1&index=1",
                   "plan": {
                       "pricingDetails": {
                           "__typename": "AppUsagePricing",
                           "cappedAmount": {
                               "amount": "875.0",
                               "currencyCode": "USD"
                           },
                           "balanceUsed": {
                               "amount": "494.9",
                               "currencyCode": "USD"
                           },
                           "interval": "EVERY_30_DAYS",
                           "terms": "$0.05 for every extra order, capped at $875"
                       }
                   },
                   "usageRecords": {
                       "edges": [],
                       "pageInfo": {
                           "hasNextPage": false,
                           "endCursor": null
                       }
                   }
               }
           ]
       }
   },
   "extensions": {
       "cost": {
           "requestedQueryCost": 26,
           "actualQueryCost": 15,
           "throttleStatus": {
               "maximumAvailable": 2000,
               "currentlyAvailable": 1985,
               "restoreRate": 100
           }
       }
   }
}

With:

  • 123123123(123123123 is replaced with original subscription id) is the new subscription id(for Pro plan)
  • Capped amount already on new Pro plan, “amount”: “875.0”
  • But balanceUsed": “amount”: “494.9” (which is the balance used/spent from old plan subscription), but the data response for usageRecords object is empty???

The subscription charge request using GraphQL with replacementBehavior value is APPLY_IMMEDIATELY as following:

mutation AppSubscriptionCreate($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!, $test: Boolean, $replacementBehavior: AppSubscriptionReplacementBehavior, $trialDays: Int) {
   appSubscriptionCreate(name: $name, returnUrl: $returnUrl, lineItems: $lineItems, test: $test, replacementBehavior: $replacementBehavior, trialDays: $trialDays) {
       userErrors {
           field
           message
       }
       confirmationUrl
       appSubscription {
           id
       }
   }
}


variable
[
 "name" => "Growth"
 "returnUrl" => ""
 "lineItems" => [
   [
     "plan" => [
       "appRecurringPricingDetails" => [
         "price" => [
           "amount" => "99.00"
           "currencyCode" => "USD"
         ]
         "interval" => "EVERY_30_DAYS"
       ]
     ]
   ]
   [
     "plan" => [
       "appUsagePricingDetails" => [
         "terms" => "$0.15 for every extra order, capped at $495"
         "cappedAmount" => [
           "amount" => 495
           "currencyCode" => "USD"
         ]
       ]
     ]
   ]
 ]
 "test" => true
 "replacementBehavior" => "APPLY_IMMEDIATELY"
 "trialDays" => 6
]

We are also noticing the balance used only update to the correct stats(reset to 0) after some hours.

Is it expected behavior or issue and if it is issue? Any workaround to fix it?

1 Like

Hey @kahn,

What you are seeing would be expected. What you’ve noted reflects the difference between your app’s billing cycle and the merchant’s billing cycle, which operate independently.

When you use APPLY_IMMEDIATELY with replacementBehavior, you create a completely new subscription (which is why usageRecords is empty and balanceUsed eventually resets).

The merchant’s Shopify admin shows $494.90 because that’s what they’ve already been charged in their current billing cycle. The $875 capped amount represents their new approved spending limit for their billing cycle. This means they can continue accruing usage charges up to $875 total, with the $494.90 already spent counting toward that limit.

https://help.shopify.com/en/manual/your-account/manage-billing/billing-charges/types-of-charges/third-party-charges/app-charges#app-usage-charges

Thank you @KyleG-Shopify for clarification.