Billing subscriptions in arrears

[Joe Shaw]

Hi,

I have a metered billing setup, and I'd like for subscriptions to be billed in arrears for the usage up to that point.  For example, you subscribe on September 19th but I don't want to bill anything until October 19th, when I would charge the fixed subscription rate plus a metered rate for the use from 9/19 to 10/19.

What's the best way to do this with Stripe?  The idea I had was to use a free trial to delay the first charge until the second month, but will this be reported oddly in invoices?  Do I have other options?

Thanks,

Joe

[Jhaura Wachsman]

We solved this by doing the following:

1. Setup a Plan with your fixed cost and a 30-day trial. This will not report oddly, as Trial Periods are fully supported in Stripe and easy to implement.

2. In your app, listen for the invoice.created webhook.

(Filter out the first invoice that is automatically generated for a new signup by looking at the invoice->paid data field = true, and the invoice->subscription->trial_end > now, so you can take actions on that first zero balance invoice as needed, different from normal invoices.)

3. When you receive the webhook, create individual Line Item(s) for your metered usage on the Invoice using the invoice->id provided by the webhook. You can add as many line items as you want/need, it sounds like you may need only one. On the Invoice, the first line item will always be the subscription itself, automatically added by Stripe. Your line items added to the Invoice will be in addition to the "subscription" type line item.

4. Within an hour or so, Stripe will automatically try and pay the Invoice and pull in your Line Items that were added after the webhook call to your app.

5. Listen for the invoice.payment_succeeded and invoice.payment_failed webhooks in your app. Take appropriate action by sending email, updating database etc.

Hope that points you in a possible direction. It's been working for us for the last 6 months very well.

[Matthew Arkin]

As Jhaura writes is the typical way to do it. 

Just some additional notes you might find helpful / useful. 

Once you enable web hooks, an invoice.creted web hook will get sent 1 hour before the invoice charge is attempted for all but the first invoice a subscription has (the first subscription is billed immediately).

If you do not respond 200 OK to that first web hook, it will get retried every hour for 72 hours, after that point the invoice will just be charged. So incase your web hook handler goes down you have a couple of days to fix it before it messes up your billing.

Matt

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at http://groups.google.com/a/lists.stripe.com/group/api-discuss/.

To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss...@lists.stripe.com.

[Joe Shaw]

Hi Jhaura,

Thank you for the incredibly detailed and clear email.  This is pretty close to what I came up with on my own and it's great to know I am on the right path. 

One last question about cancellations: do you simply listen for a cancellation webhook and then create and pay an invoice for the prorated portion? Since we are billing in arrears we want to make sure we bill for that final portion. 

Thanks again,

Joe

--
You received this message because you are subscribed to a topic in the Google Groups "Stripe API Discussion" group.

[Jhaura Wachsman]

Yeah, cancellations are a bit harder with arrears. The reason is, that you will not have a final Stripe generated invoice to listen for, since subscriptions are "pre-paid". You'll instead have to manually create your own, using the customer.subscription.deleted webhook as the queue.

What we do is to listen for the deleted webhook, then because you have metered billing that needs to be done still, you need to: (1) add final line items (not attached to any invoice id or subscription), (2) create a manual invoice, (3) and then pay it right away (or just wait the 1-2 hours and Stripe will auto-pay it). The key is to add your line items prior to manually creating your final invoice so it can pick them up. It's a bit odd to me, but in Stripe you can't create a blank invoice and then attach line items, so you can't take advantage of automating the line item parts off a webhook.

The downside to manual invoices is that they are not of the "subscription" type and make it a little harder with reporting in your own app, but it's the only way I know of...perhaps someone with a better solution will chime in and help us out.

I'm sure you know from experience too, there are issues when the final invoice payment declines and you are stuck with "collections". The achilles heel of post-paid type products/services. Not fun to try and account for in the app.

Cheers ~J

On Sunday, September 21, 2014 11:41:56 AM UTC-7, Joe Shaw wrote:

Hi Jhaura,

Thank you for the incredibly detailed and clear email.  This is pretty close to what I came up with on my own and it's great to know I am on the right path. 

One last question about cancellations: do you simply listen for a cancellation webhook and then create and pay an invoice for the prorated portion? Since we are billing in arrears we want to make sure we bill for that final portion. 

Thanks again,

Joe