Ajay Sridharan

If you want your analytics to work out-of-the-box, there are some things you shouldn’t do with the Stripe API.

The following are all valid ways to use the API, and some of them are even presented in official Stripe documentation, but make no mistake: doing these things can break your metricsIn some cases the data can be patched to get the metrics right, but that’s always extra effort for you. 

Here’s how to avoid that:

1. Don't lose money when refunding prorated subscriptions

When you refund a subscription during a plan change, do the following:

  1. Give the refund
  2. Delete/close the old subscription
  3. Create the new subscription

Another option is to run the subscription change with a prorate:false option that disables prorations.

If you don’t refund the full amount, you’ll have to modify account_balance by the amount refunded instead.

What’s the problem with doing this?

You may accidentally waive a customer’s fees for several months.

Refunds aren’t reduced from the subscription amount in the prorationSo even though you refunded the subscription, the subscription will be prorated as if no refund had happened—and the customer now has account_balance from where he can pay his future fees.

2. Avoid using account_balance

Try to avoid modifying a customer’s account_balance.


Because amounts charged or discounted via account_balance may not get booked right.

In many cases it’s impossible to differentiate the account_balance that you set from the account_balance that Stripe sets when doing prorations. recognizes setup fees from balance, but not discounts or non-Stripe payments.

You can’t always avoid using account_balance, but avoid using it when possible.

Here are a couple examples of what you can do instead:

Give discounts with discount coupons, not with account_balance or by invoicing items with a negative amount

When you create a proper discount coupon, you can be sure that the discount will get booked right.

Charge setup fees with an extra invoice item, not with account_balance

When you create an invoice item before creating the subscription for the customer, the setup fee gets charged in its own line with the first invoice—and the analytics apps will know it’s a separate charge.

Do use account_balance when the customer pays in advance

If the customer wants to pay their subscription in advance, you can create a charge that puts the amount paid to their account balance.

This balance will be used to pay for their subscription later and FirstOfficer recognizes the MRR.

3. Only create one cent plans if you really use them

Stripe API allows you to create $0.01 plans, which don’t get charged until the balance exceeds $0.50.

You might be tempted to put all your free users onto this plan and sneak them into the system. Don’t do that.

Why not?

Your metrics will get watered down with users that should be excluded from the numbers. The cent plans are meant for capacity-based charging, so they will be processed.

4. Avoid renaming plans if you have prorations before August 2014

If you have prorations that were created before August 2014, consider creating a new plan instead of renaming an old plan.

If you rename plans, make sure your new plan name does not overlap with the old ones.

Why is that important?

Because all upgrades and downgrades may not get booked to the right plans.

Since 2014/7/22, Stripe API now returns plan_id with prorated lines, but some older lines still don’t have them and the plan name needs to parsed from the description.

You can contact support and we can check if it’s safe to rename plans.

5. Avoid deleting Stripe customers when customers are lost

Do clean up credit card information and any other information that you aren’t allowed to keep, but do not delete the customer from Stripe, if possible.

Why not?

Although you might not be thinking about it now, you need to be able to identify your old customers: in case they come back, for example, or in case you want to try to win them back.

6. Don't create a new Stripe customer for returning customers

When a customer returns, reuse their old Stripe customer account.


Because if you don’t, returning customers will get booked as new customers, payments from the same source will get scattered across different Stripe customers, and Total Contract Values won’t be calculated accurately.

7. Only use 3rd party subscription plugins that create Stripe subscriptions

Many plugins that help you manage Stripe subscriptions bypass Stripe subscriptions altogether.

There are some plugins, like Koudoku and Payola, that do use Stripe subscriptions and work with analytics apps. However, at the time of writing Payola is using account_balance to handle setup fees.

What’s the problem with this?

If you don’t use Stripe subscriptions your revenue will be booked as single charges instead of MRR.