Billing FAQ
Find answers to common questions about billing, plan management, and usage tracking in Mantle.
Frequently asked questions
What happens to the billing cycle when a customer changes plans?
When a customer changes their plan, a new billing period is set starting from the date the new plan is approved and running for the next 30 days. The customer won't stay on their previous billing cycle. If there's a difference in plan pricing, the charges will be prorated accordingly.
When are usage charges billed?
You can configure when usage charges are billed in your app's settings. Options include immediate billing, monthly billing, or calendar month billing.
How do usage charges work near the cap limit?
Currently, Mantle doesn't process partial usage charges. If a set of usage events would exceed the customer's cap limit, no charges will be processed for that set. For example, if a customer has a $19.99 cap and has used $18.00, a new usage event worth $2.20 would not be charged at all (rather than charging the remaining $1.99).
How is usage tracked across billing periods?
Usage is tracked within each billing period. The currentBillingPeriodValue shows usage for the current period. Usage counting starts fresh when a natural billing cycle renews (every 30 days) or when a trial ends. However, plan changes preserve usage unless you enable the "Reset usage limits" setting under Your app → Settings.
Do trials reset if you uninstall and reinstall?
No. A trial begins when a customer first starts it and continues regardless of uninstalls or plan changes. If a customer has a 7-day trial, uninstalls, then reinstalls within those 7 days, the trial continues with the remaining days. After the trial period ends, resubscribing won't grant any new trial days.
Does usage reset when a trial ends?
Yes. While usage is tracked during the trial with currentBillingPeriodValue, a new billing period starts when the trial ends. Any usage during the trial will be included in that period's calculations.
Is the trial period a separate billing period?
Yes. The trial has its own currentPeriodStart and currentPeriodEnd dates. When the trial ends, a new billing period begins with its own start and end dates.
Can I charge a customer during a trial?
You can't charge a customer a recurring application charge as that only charges after a trial is over but you can charge usage and one-time charges.
How are customers notified of automatic upgrades?
Mantle offers webhook notifications for plan changes. Configure these through our webhook guide.
When is my customer charged for their plan?
Flex billing is similar to a regular recurring charge, but instead of using a recurring application charge, it bills the monthly plan price as a usage charge. Customers are billed right away for their monthly plan.
When is my customer charged if they are automatically upgraded to a new plan?
When a customer gets upgraded to a new plan with flex billing, they'll be charged right away for the new plan. Any price difference is prorated.
Is usage tracked during a trial period on flex billing and can a customer be upgraded during a trial?
No, while usage is tracked during trial, a customer wouldn't be able to be upgraded to a plan during a trial as that plan would charge them right away and a customer shouldn't be billed during trial.
Do customers automatically downgrade at the end of a billing period?
No, customers stay on their current plan even after the billing period ends. They'll remain on the plan they were upgraded to until they manually choose to switch to a different plan.
Can I disable flex billing on plans and use them as regular plans?
No, you should create new plans specifically for flex billing. Once flex billing is enabled on a plan, it can't be turned off.