Glossary

Stripe Invoice Payment

A Stripe InvoicePayment is the object that records the mapping between a payment, such as a PaymentIntent, and the invoice it was applied to, including how much of that payment was allocated to that particular invoice.

Also called: InvoicePayment, invoice_payment, invoice payment object, payment allocation

Start a free trial View Pricing

Definition

Reconciliation is not really a question about money. It is a question about attribution. You can see that 2,000 arrived. What you need to know is which invoice it settled.

A charge does not answer that. A charge knows it succeeded, for how much, against which customer and payment method. The invoice it belongs to is not part of what a charge is.

InvoicePayment is the object built for the missing half. Stripe describes it in one line: "Invoice Payments represent payments made against invoices." The more useful sentence is the one that follows, which states what the resource is actually for: "Invoice Payments include the mapping between payment objects, such as Payment Intent, and Invoices. This resource and its endpoints allows you to easily track if a payment is associated with a specific invoice and monitor the allocation details of the payments."

Allocation is the operative word. This is not simply a pointer from a payment to an invoice. It records how much of a payment went to that invoice, which only matters because the two numbers are allowed to differ.

Key points

+Stripe: "Invoice Payments represent payments made against invoices."
+It carries "the mapping between payment objects, such as Payment Intent, and Invoices".
+Reachable two ways: by expanding the payments field on an Invoice, or through the InvoicePayment retrieve and list endpoints.
+The invoice object describes its own payments field simply as "Payments for this invoice."
+amount_requested is the "Amount intended to be paid toward this invoice", while amount_paid is what was actually paid.
+amount_paid "is null until the payment is paid", so an open payment has no paid amount yet.
+status is "one of open, paid, or canceled", with matching paid_at and canceled_at timestamps.
+Stripe "automatically creates a default InvoicePayment when the invoice is finalized, and keeps it synchronized with the invoice’s amount_remaining".
+The PaymentIntent behind that default payment "can’t be edited or canceled directly".
+The invoice_payment.paid event "Occurs when an InvoicePayment is successfully paid."

Why the requested and paid amounts are two different fields

At first glance a payment record holding two amounts looks like redundancy. It is not, and the reason is the most interesting thing about this object.

Stripe defines the first as the "Amount intended to be paid toward this invoice", and the second as the amount "that was actually paid for this invoice". Then it explains exactly when they diverge: the paid amount "can be less than the amount_requested if the PaymentIntent’s amount_received is not sufficient to pay all of the invoices that it is attached to".

Read that once more, because it contains a fact that surprises people: a single PaymentIntent can be attached to more than one invoice.

Once that is true, a payment stops being a scalar and becomes something that has to be divided. If one PaymentIntent is attached to three invoices and the money received does not cover all three, something has to decide how much of it each invoice gets. The InvoicePayment for each invoice is where that decision is recorded.

So the pair of fields is the difference between intent and outcome, per invoice. What we meant to put here, and what actually landed here. For anyone reconciling, the second number is the one that belongs in the books.

The default payment Stripe creates for you

You do not have to create an InvoicePayment for the ordinary case, because Stripe already did.

The documentation on the is_default field describes the mechanism: Stripe "automatically creates a default InvoicePayment when the invoice is finalized, and keeps it synchronized with the invoice’s amount_remaining".

Two things follow from that, and both are practical.

The first is that the default payment exists from finalization onward, not from the moment money moves. It is created with the invoice, and it tracks the outstanding balance as that balance changes. It is the invoice’s standing expectation of being paid.

The second is a constraint worth knowing before you try to work around it. Stripe states that the PaymentIntent associated with the default payment "can’t be edited or canceled directly". That is deliberate. The default payment is Stripe’s own bookkeeping for the invoice, kept in step with the amount remaining, and letting an integration cancel it out from underneath would break the synchronisation it exists to maintain.

Two ways to reach it

Stripe gives the resource two access paths, and says so directly. Invoice Payments "can be accessed in two ways: 1. By expanding the payments field on the Invoice resource. 2. By using the Invoice Payment retrieve and list endpoints."

The choice between them is really a choice about direction.

Start from the invoice when the invoice is the thing you care about. You already have it, you want to know what has been paid against it, and expanding its payments field gets you the answer in the same call. The invoice object describes that field plainly as "Payments for this invoice."

Start from the endpoints when you are working the other way, or in bulk. Retrieving one InvoicePayment by id, or listing them, suits a reconciliation job walking a period rather than a single document.

For event-driven work there is a third entry point. Stripe emits invoice_payment.paid, which "Occurs when an InvoicePayment is successfully paid." That is the moment the attribution becomes final, which makes it a natural trigger for anything that needs to record a settled invoice rather than merely a received payment.

Status, and the timestamps that go with it

The status field is short: "one of open, paid, or canceled".

Open means the allocation exists and is expected but has not completed. This is the state the default payment sits in for an unpaid finalized invoice.

Paid means the money has been attributed. This is where the amount actually paid becomes meaningful, and it is worth remembering that until this point the paid amount "is null until the payment is paid". Treating a null as a zero is a small mistake that quietly turns "we do not know yet" into "nothing was paid".

Canceled means the allocation will not complete.

Alongside the status sits a small object of transitions carrying paid_at and canceled_at, which is where you look when the question is not what happened but when. For accounting, that distinction is the whole game: the date a payment is attributed to an invoice is what decides the period it lands in.

Where this sits relative to a charge

It helps to hold three objects apart, because they answer three different questions and people routinely expect one of them to answer all three.

A charge, or the PaymentIntent behind it, answers "did money move, and how much". It is the fact of the payment.

An invoice answers "what was owed, by whom, for what". It is the claim.

An InvoicePayment answers "which payment settled which claim, and for how much of it". It is the link, and the link is the piece reconciliation actually runs on.

This is why a reconciliation built only on charges gets uncomfortable at the edges. The straightforward cases look fine, because one charge settling one invoice needs no explicit mapping to be obvious. The trouble starts wherever the relationship stops being one to one, and that is precisely where the object holding the allocation stops being optional.

How this relates to Acodei

Acodei’s product documentation describes the QuickBooks side of the same question rather than this Stripe resource.

When a Stripe invoice is paid, whether by a successful charge, a manual payment according to your settings, or a credit balance offset, Acodei creates a QuickBooks Payment Receipt or Credit Memo and applies it to the invoice it had already created. The documented triggers for that payment record are the invoice.paid and charge.succeeded events, and the automatic application depends on QuickBooks Automatic Application being switched on.

Two of Acodei’s validation rules apply specifically when it records an invoice payment, and both are about exactly the attribution this glossary entry is describing: that the correct payment amount is applied to the QuickBooks invoice, and that the payment is properly linked to the correct QuickBooks invoice.

One honest boundary. Acodei’s documentation does not describe reading Stripe’s InvoicePayment resource itself, so treat the Stripe object as the place to look when you want Stripe’s own view of an allocation, and the QuickBooks records as the place to check what was written into your books.

If you want the payment recorded against the right invoice without doing it by hand, see how Acodei records the payment against the invoice it created.

Want to see this on your own Stripe data?

Start a free trial

Frequently asked questions

What is a Stripe InvoicePayment?

It is the object recording that a particular payment was applied to a particular invoice, and for how much. Stripe describes Invoice Payments as representing "payments made against invoices" and as including "the mapping between payment objects, such as Payment Intent, and Invoices". Where a charge tells you money moved, an InvoicePayment tells you what it settled.

How is an InvoicePayment different from a charge?

A charge is the movement of money and knows nothing about which invoice it belongs to. An InvoicePayment is the link between a payment object and an invoice, together with the amount allocated to that invoice. They answer different questions, and reconciliation needs the second one.

Why does amount_paid differ from amount_requested?

Because one payment can be attached to several invoices. Stripe states that the amount paid "can be less than the amount_requested if the PaymentIntent’s amount_received is not sufficient to pay all of the invoices that it is attached to". The requested amount is what was intended for that invoice, the paid amount is what it actually received.

Do I have to create an InvoicePayment myself?

Not for the ordinary case. Stripe "automatically creates a default InvoicePayment when the invoice is finalized, and keeps it synchronized with the invoice’s amount_remaining". Note that the PaymentIntent associated with that default payment "can’t be edited or canceled directly".

How do I find the payments for a Stripe invoice?

Two ways, per Stripe: expand the payments field on the Invoice, which the invoice object describes as "Payments for this invoice", or use the InvoicePayment retrieve and list endpoints. Expanding suits working from a single invoice; the endpoints suit bulk or reverse lookups.

What statuses can an InvoicePayment have?

Stripe documents the status as "one of open, paid, or canceled", with a transitions object holding paid_at and canceled_at. Worth knowing: the paid amount "is null until the payment is paid", so an open payment has no paid amount rather than a zero one.

Is there a webhook for invoice payments?

Yes. Stripe emits invoice_payment.paid, which "Occurs when an InvoicePayment is successfully paid." It marks the point at which the attribution of a payment to an invoice is final, which makes it a sensible trigger for anything recording settled invoices.

What customers say about running Stripe through Acodei

★★★★★

“If you're testing out all the different Stripe/QuickBooks integration apps right now, let me save you some time. This one is the best one by far.”

RyanOwner at Indie Music Academy