Usage-based billing: When capped amounts aren't easy to predefine

Shopify Partner
17 0 6

Hello all

My app (under development) has two pricing components:

  • Recurring monthly subscription fee
  • Usage-based, per order fees

So far, I've implemented the billing API to handle the recurring fees, but now I've turned to figuring out usage fees, and hadn't noticed that the cappedAmount argument is required to set up a billing plan for these.

Our app's core function is to charge merchants for every order associated with our app. Since we don't know in advance how big or small a merchant's order volume would be, I'm unsure of what the best strategy is for implementing a predefined capped amount when they set up billing.

Firstly — I'm assuming there is no way to set an "uncapped" usage-based plan for a store? It goes without saying that the merit of capped billing is quite clear, but it would be great to offer the merchant an option when usage is unknown.

Secondly — What's the protocol for dealing with capped amounts when the potential usage isn't easy to predefine?

The best I can come up with right now is a UX flow that:

  • Informs the merchant that our app has usage-based charging
  • [Asks them to estimate / choose a monthly limit that would reflect their expected usage]
  • Implements a custom cappedAmount in the plan creation call
  • Notifies them when they hit the capped usage amount — and asks them to re-run a billing flow with a new capped amount

I see from the advice to merchants that their expected behaviour is:

To continue using an app after exceeding a capped amount, you need to agree to a new usage charge. This prevents you from being charged for any usage over and above the capped amount.

This seems a little cumbersome to me, as having to ping a merchant when they want to continue fulfilling their orders (through our app), and also implementing "spill-over" / unpaid fee functionality is a lot of extra engineering, and potentially annoying merchant UX (again, understand this is balanced by the safety of billing caps).

I couldn't find any examples in the billing documentation that focus on this use case specifically.

Does anyone have any experience doing this or the best practices / flows for implementing it?


Thanks in advance!



Replies 8 (8)

1 0 3

+1 for this. Find anything out?

Shopify Partner
2 0 2

+1 We're running into the same issue. Any updates or solutions you've found helpful?

7 0 4

+1 Also an issue for us

3 0 1

+1 from me, the whole billing system is user UNfriendly. It would make most users run a mile.

23 1 21

I am sure you figured it out by now, but the way to get what you want (the way I figured it out anyway) is as follows;


1. Create the recurrent fee with

  1. A price of your monthly fee, for example $5
  2. A large capped_amount (large enough that it would be higher than any bill you might want to throw at a customer) for example $1000

2. Add whatever usage based fees as they are incurred by the customer

This will bill the customer every 30 days and the bill will look like this:

$5 - monthly fee

$2 - usage fee #1 

$3 - usage fee #2

... etc 


As long as the sum of those usage fees don't go above the capped_amount there is going to be no extra steps of approval or other fuzz


So in the case where you don't know the usage fees, then you will have to keep track of the billing cycle and accumulate the usage in your database until the day before billing, then aggregate and add the usage fees that match then. One way to do this is to have a scheduler/cronjob that runs once every 24 hours and checks for each customer if the billing will occur tomorrow, and if that is the case, calculate and POST the usage fee and then mark the usage as paid in your own database.
3 0 1

Yeah this is one option. 

If you set it thag high you have the issue that users will see “additionally charges may blah blah…$100,000” the drop off for that would be insane.

im setting up a we hook that fires every 12 to check  all installs for who might need this additional amount amount. 

3 0 1

I’ve since looked at setting up a cronjob through google cloud to fire at 6-12 hour intervals(not decided yet, need more data)


this will replenish the capped amount if it drops below an amount.


cheers for the help all!

Shopify Partner
84 4 20

@DJMitts curious if you've gotten very far on this yet. The chron job can identify IF you need to increase the capped amounts, but they need to approve it, so you'd need to notify them via email or in your app to have them navigate to a shopify url to approve the increase, right? And I can't find details in the documentation that explains how to pass the callback url to your app with the merchant's approval or disapproval result.

You can see the `appSubscriptionLineItemUpdate` does not have a `returnUrl` argument like the `appSubscriptionCreate` does. So after the merchant approves or do you know? I guess you could implement another cron job to check the status 5 min later and re-notify the merchant it if wasn't updated...but that is not a great design and would be much better if you could react to the approval or disapproval directly and interactively with the merchant.

Chad Richardson
Mozzo Software - Modular Software that grows with you from solopreneur to a 200 person mega team. Why keep outgrowing your Shopify Apps? Start with us, and just use the modules you need, then add more as you grow.