Stripe-specific configuration for balance handling

This is just a draft (this needs to be made into a proper article).

This option is OFF by default. It can only be be enabled by someone at ChartMogul, there's no way to enable this option in the UI.

The switch is on the Stripe data source:

It is OFF (we will not generate balance_manual) for all new accounts that add Stripe data source. If account already has Stripe data source it will preserve the same stripe_manual_balance_handling setting as existing Stripe data source. Once again:
- if there is already a Stripe data source and it has this setting ON => new data source will have it ON
- if there are no Stripe data sources or all of them have setting OFF => new will also have OFF
I think this is the most expected behaviour.


Enabling this option also has the potential to impact cash flow charts.

Pasted from conversation with Calendly - :

We were able to replicate the exact situation you have in your account. With relation to these balance items. What we believe you do is:
- Customer subscribes to an annual plan
- Then downgrades to monthly => Stripe adds a credit to the customer's balance
- Calendly partially refunds the original subscription payment (the amount of the refund is equal to the amount of credit applied in previous step)
- Calendly manually (or via API) removes all credit from the customer’s balance

This last step causes us to generate these balance_manual line items which are causing you issues with RevRec.

What is balance_manual?

There are two ways a customer in Stripe can have their account balance modified:

1) By changes to the customer's billing configuration, e.g. a downgrade.

2) Manually, by just modifying the balance amount in the Stripe UI or via API.

For the purposes of Revenue Recognition we do not recognize balance items generated by changes to the customers billing setup (e.g. by a downgrade).

However, for the purposes of Revenue Recognition we do recognize explicit alterations to a Stripe customers' balance (e.g. made in the Stripe UI or via API) because technically these alterations usually represent a real movement of money.

Using the original example: money credited following the the downgrade was paid at some point. If not removed from the balance, that credit would be used to pay off future payments, so removing this balance has a real impact on revenue, which we track and generate a line item called 'balance_manual'.

The reason why this logic doesn’t work for Calendly is that you refund the original amount AND remove the balance. The combination of refunds and manual balance removal creates a double negative, which we account for by generating these balance_manual items.

The above logic of recognizing these manual balance adjustments is the problem, so we've been asking ourselves, should we make this logic optional (or remove it completely) from ChartMogul?

  • If a customer has a standard process for handling downgrades (i.e. they do the steps above - subscribe, downgrade, refund, remove credit), then making this logic optional would be work fine.
  • If it is not a standardized process across your Stripe account then disabling this logic would create a mess, because there would be inconsistency in how things are handled and the Revenue Recognition schedules would not add up.

So as a next step, could I ask how uniform the above steps are? Is it done manually by a user or it's handled automatically via code?

To fix your RevRec in ChartMogul we need to remove these balance_manual line items from your account completely.

The slightly cleaner way to handle these situations in Stripe is to do a non-pro-rated downgrade, and then make the refunds, this bypasses the above logic altogether and our Revenue Recognition works fine. I'm assuming the reason it is setup like this on your end, is because if you do a pro-rated downgrade, then Stripe calculates (via the credit that's applied) the exact amount you need to refund to the customer.