Difference between invoice line items and invoice items?

[Josh Pigford]

Is there a difference between invoice line items and invoice items?

https://stripe.com/docs/api#invoice_line_item_object

https://stripe.com/docs/api#invoiceitems

They seem really similar but their attributes don't quite match up.

[Jim Danz]

Considering an invoice, an invoice is composed of one or more invoice
line items.

An invoice line item can (currently) have one of two types:
"invoiceitem" or "subscription".

A "subscription" line item is a billable for a standard subscription
billing period -- created due to subscription creation, or created due
to automatic rebilling of a subscription at the end of the month.
Hence, there is no direct way in the API to specify "create a
subscription line item"; the API operations are always at the level of
"subscribe my customer to plan Foo," which will lead to the creation
of a subscription line item.

A "invoiceitem" line item is a reference to an invoice item.
Considering invoiceitem ii_foo, when invoice in_bar has a line item
that points to ii_foo, this means that ii_foo was billed on in_bar.

And essentially, what the "invoice line item" object is is an attempt
to pull distill subscription line items and invoiceitem line items
down to their common properties, so that when you're looking through
the all of the line items on an invoice, each object that your'e
looking at has the same structure.

More than happy to answer any followup questions.
Jim

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

[Josh Pigford]

All that make sense...almost. :)

I see "invoiceitem" can have a subscription. That seems odd to me as in my head an invoice would have "subscriptions" and "invoiceitems"...but the face that "invoiceitems" could have a "subscription" makes my head spin. :)

When would an "invoiceitem" have a "subscription"?

[Jim Danz]

Hi Josh,

Ah, good question. Since the launch of multiple subscriptions per
customer, it has been possible to specify, when creating an invoice
item, that that invoice item should "bill on" a particular
subscription. [1]

Concretely, suppose that a customer has 2 active subscriptions:
1) sub_a, bills on the 15th of the month
2) sub_b, bills on the 30th of the month

When an invoice item is created without a specified subscription id,
it will be picked up the next time any active subscription is
invoiced. So, if you created an invoice item on the 13th, it'd bill
with sub_a on the 15th. If you created an invoice item on the 20th,
it'd bill with sub_b on the 30th.

Supposing it's the 13th of the month and you want to create a billable
that you know will bill on the 30th with sub_b, you can do so by
specifying subscription=sub_b at invoice-item-creation-time.

Additionally, since the launch of multiple subscriptions, proration
invoice items always know about which subscription they bill on. This
is the mechanism by which, supposing that I upgrade sub_b from the
"silver" plan to the "gold" plan on the 5th of the month, we know not
to invoice those prorations until sub_b bills again on the 30th of the
month.

So, in summary:
* proration invoice items created since 2013-11-14 should always have
non-nil subscription
* most other invoice items will likely have nil subscription, unless
subscription was explicitly set by a multi-subs user

Jim

https://support.stripe.com/questions/whats-new-with-multiple-subscriptions-per-customer-january-2014