There are some things you shouldn't do with the Stripe API, if you want your analytics to work out-of-the-box.

These are valid ways to use the API and some of them are presented in Stripe documentation - but they can break your metrics.

In some cases the data can be patched to get the metrics right, but that's always extra effort for you.

1. DON'T LOSE MONEY WHEN REFUNDING PRORATED SUBSCRIPTIONS

When you refund a subscription during a plan change:

• Give the refund

• Delete/close the old subscription

• 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 the account_balance by the amount refunded instead.

What's the problem?

You may accidentally waive customer's fees for several months.

The refunds aren't reduced from the subscription amount in the proration.

So even though you refunded the subscription, the subscription will be prorated as no refund had happened - and customer now has account_balance from where he can pay his future fees.

2. AVOID USING ACCOUNT_BALANCE

Try to avoid modifying Stripe API customer's account_balance.

What's the problem?

Amounts charged or discounted via account balance may not get booked right.

In many cases it's impossible to differentiate account_balance that you set from the account_balance that Stripe sets when doing prorations, so the support cannot be added.

FirstOfficer.io 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 of examples:

Give discounts with discount coupons, not with account_balance or invoice items with negative amount

When you create a proper discount coupon and set to the customer, you can be sure that the discounts 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 it's own line with the first invoice - and analytics apps will know it's a separate charge.

Do use account balance when customer pays in advance

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

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

3. ONLY CREATE 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 your free plan users to this plan and sneak them into the system. Don't do that.

What's the problem?

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.

What's the problem?

All upgrades and downgrades may not get booked to 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 the credit card information and any other information that you aren't allowed to keep, but do not delete the customer from Stripe, if possible.

What's the problem?

When your metrics are shown, you can't identify your old customers.

6. DON'T CREATE A NEW STRIPE CUSTOMER FOR RETURNING CUSTOMERS

When a customer returns, reuse his old Stripe customer.

What's the problem?

The returning customers will get booked as new customers.

The Total Contract Values can not be calculated accurately when payments are scattered in different Stripe customers.

You will have extra trouble if you need to find out everything that the customer did.

7. ONLY USE 3RD PARTY SUBSCRIPTION PLUGINS THAT CREATE STRIPE SUBSCRIPTIONS

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

There are some plugins, like Koudoku and Payola, which do utilise 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?

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