Invoice period_end (at subscription creation and on rebilling) not what I expected

[jay...@pandodaily.com]

The invoice.payment_succeeded event that comes when a subscription is created (and particularly for us when a customer is created with a listed plan) seems to have period_end equal to period_start, both set to now-ish. However the subscription line item has the correct period.

Invoices triggered by rebilling of a subscription seem to list end of period as the start of the subscription period to be billed, with start of period of the invoice being more like original creation of the subscription / customer. I can't be 100% certain of this, because we've upgraded API use to do this latest block of development; the previous API we were on (from last year sometime) was I believe behaving as I expected. (Rebilling invoices I'm figuring out by looking at the upcoming invoice for a customer, so it may not be exactly what appears when it gets created for real.)

My question is just: what's the simplest way of figuring out the *end* of the period that an invoice has paid for (we use this for advancing eligibility for a print artefact that doesn't match the billing cycle, and has a rule that if you've paid for any of the period since the previous one, you get this artefact)? It looks like subscription lines in the invoice are the most reliable, but it also looks like the period start & ends on invoices aren't particularly consistent or meaningful, and certainly don't seem to match what I was expecting from the API documentation.

Best,

James

[Jim Danz]

Hey James,

Thanks for writing in to clarify this, and sorry that our docs don't
do a better job here.

The short answer is that the subscription lines in the invoice sound
like the right thing to look at for your need (advancing eligibility).

The long answer is that this is due to the way that we think about
accruing billables.
Essentially the invoice period is the "period over which billables
accrued" for the invoice, and the subscription period is the "time
period that the customer is paying for." Hence the off-by-one factor
between the invoice period and the subscription period: you accrue
billables in period X, and at the end of period X, you pay for the
subscription period X+1.

For a concrete example, suppose a monthly subscription is created on May 1st.
The initial invoice will have period_start == period_end == now-ish,
as you've observed. Basically this is a fresh subscription and there
is no previous time over which billables accrued, so to speak. And
the subscription period paid for will be May 1st - June 1st.

When June 1st rolls around, the invoice that is created will have
period May 1st - June 1st, as it will include any invoice items that
were accrued over the month of May. Additionally, it will include the
subscription charge for June 1st - July 1st.

So if you're looking at an invoice and asking "when this invoice gets
paid, until what point will this customer's subscription be fully paid
off?" the answer is the period end on the subscription line item.

Cheers,
Jim

P.S. I don't believe that any of this has changed with API versions,
though I'd be happy to double-check if you can recall which version
you were previously on.

> --
> 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.

[James Aylett]

On 17 Apr 2014, at 12:14, Jim Danz <j...@stripe.com> wrote:

> Essentially the invoice period is the "period over which billables
> accrued" for the invoice, and the subscription period is the "time
> period that the customer is paying for." Hence the off-by-one factor
> between the invoice period and the subscription period: you accrue
> billables in period X, and at the end of period X, you pay for the
> subscription period X+1.

Ah, I see. The current API docs say:

period_end (timestamp)
End of the usage period the invoice covers
period_start (timestamp)
Start of the usage period the invoice covers

It might be worth rewording that, and maybe calling out what "invoice period" means in the opening summary for invoices in the API docs.

> So if you're looking at an invoice and asking "when this invoice gets
> paid, until what point will this customer's subscription be fully paid
> off?" the answer is the period end on the subscription line item.

Great; I was already changing to use that, but this gives me confidence there won't be weird corner cases.

> P.S. I don't believe that any of this has changed with API versions,
> though I'd be happy to double-check if you can recall which version
> you were previously on.

No, looking back at some previous data I don't think this is new. But it's new functionality for us, so I don't think we ever cared about invoice dates at all before now.

Thanks!

Best,
James