Represent upcoming invoices separately from invoices with ids

[bryanburgers]

When using the upcoming invoice endpoint, the response represents an invoice that doesn't exist yet, and does not have an id.

Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer’s discount.

The openapi spec for Invoice here, however, does not mark id as nullable: true. Which means that code generators will not make it optional, and could fail while parsing.

[brandur-stripe]

Thanks for logging!

Hmm, the trouble with this endpoint is that it points back to a "standard" invoice API resource, which seems largely desirable, but of course id is wrong.

We have a few possibilities to:

• Create a separate, duplicate resource for an upcoming invoice.
• Return a symbolic value representing nilable in id.
• Mark id on the standard invoice API resource as nilable.

I've filed a ticket with the internal team responsible for Stripe's Billing products to see what they want to do.

[broccolihighkicks]

When listing invoices, will they always have an id?

This must be true as the pagination starting_after key takes the id of the last invoice in the array?

[remi-stripe]

Yes invoices will always have an id. Only the upcoming invoice endpoint returns a nullable id, and those can't be "listed" or use pagination.