When to charge for monthly usage at end of billing cycle in stripe

Question

I have a subscription plan which costs $10/month per user plan + data "overage" charges. In other words, it is similar to (not unlimited) cell phone data plan.

When should I add in the monthly data usage at the end of the cycle?

According to Subscription lifestyle documentation here , it says that the invoice.created event occurs roughly an hour before the invoice.payment_succeeded or charge.succeeded . However, it seems almost impossible to test this, as whenever an invoice is first created for a subscription, all the webhook events seem to fire simultaneously. How should this be dealt with? Note that I only want to update the metered usage amount one time, at the end of the cycle.

My code is currently something like this:

def stripe_webhook(request):

    if event_type == 'invoice.created':

        subscription_item_id = [item['subscription_item'] for item in stripe_data_obj['lines']['data'] if item['plan']['usage_type'] == 'metered'][0]

        data_usage = user.get_data_usage(start_date, end_date)
        usage = stripe.UsageRecord.create(
          quantity=data_usage,
          timestamp=int(time.time()),
          subscription_item=subscription_item_id,
          action = 'set'
        )

Answer 1

If you want to manually add line items to the invoice, then you can definitely test this. The idea would be to put your customer on a trial period for a few minutes. The first invoice created is for the trial and you can ignore that one and all related events. A few minutes later, when the trial period ends, a new invoice will be created and an invoice.created event will be sent to your endpoint. That one will allow you to modify the new invoice and add the extra amount/fees to charge this month.

To do this, you would use the Create Subscription API and pass the trial_end parameter as a unix timestamp representing a few minutes in the future.

Separately though, if you really want to report over-usage, you could use metered billing and usage records as documented here: https://stripe.com/docs/billing/subscriptions/metered-billing