Stripe Customer

The fields that end up in your books

The Customer object has a couple of dozen attributes. For anyone reconciling Stripe against QuickBooks, a handful do almost all of the work.

name is documented by Stripe as "The customer’s full name or business name". It is the field most integrations reach for first when they need something to call the payer. email is "The customer’s email address", and it is usually the only other identifier that is reliably present.

There are two addresses, and they are not interchangeable. address is "The customer’s billing address". shipping is "Mailing and shipping address for the customer", and Stripe notes that it "Appears on invoices emailed to this customer." A business that ships goods may have both filled in and different.

The tax fields decide how invoices are taxed and labelled. tax_exempt "Describes the customer’s tax exemption status, which is none, exempt, or reverse", and when it is set to reverse, "invoice and receipt PDFs include the following text: Reverse charge." tax_ids holds the customer’s tax registration numbers.

Finally, currency is the "Three-letter ISO code for the currency the customer can be charged in for recurring billing purposes." It is a billing default, not a statement about which currency every payment from that customer will arrive in.

Invoices take a snapshot, and the snapshot freezes

This is the behavior that explains most "the invoice shows the old address" questions.

A Stripe invoice does not just point at its Customer. It keeps its own copy of the customer’s details, and Stripe documents the rule the same way for every copied field. For customer_name: "Until the invoice is finalized, this field will equal customer.name. Once the invoice is finalized, this field will no longer be updated." The same wording applies to customer_email, customer_address, customer_phone, customer_shipping and customer_tax_exempt, and customer_tax_ids follows the same pattern.

So if a customer moves in May and you update their Customer record, every invoice finalized before that change still shows the old address, and it always will. Think of a finalized invoice as a document that was issued to someone: it keeps reading the way it read when it was sent.

The practical consequence is that Stripe can hold three different versions of one customer at once: the live Customer record, the frozen copy on each finalized invoice, and whatever was typed into the payment form on each individual charge. When two systems disagree about a customer’s details, the first question is which of those three each one read, and when.

Payments that have no Customer at all

Plenty of Stripe charges are never attached to a Customer. Stripe documents the charge’s customer field as nullable, the "ID of the customer this charge is for if one exists."

What a charge always has instead is billing_details, which Stripe describes as "Billing information associated with the payment method at the time of the transaction." For a one-off card payment, that is often the only name and address anywhere in Stripe.

The two sources behave differently over time. A Customer can be edited, and edits flow into anything that reads it live. billing_details belongs to one transaction and describes that moment only. A buyer who pays three times without a Customer record leaves three separate sets of billing details, which may not match each other.

For your books this is the case to plan for rather than discover. If a large share of your revenue arrives without a Customer, the name on the corresponding accounting record has to come from somewhere else, or it has to come from a rule you chose in advance.

The balance field is not your receivables

balance looks like it should tell you what a customer owes. It does not.

Stripe describes it as "The current balance, if any, that’s stored on the customer in their default currency. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that’s added to their next invoice." The next sentence is the important one: "The balance only considers amounts that Stripe hasn’t successfully applied to any invoice. It doesn’t reflect unpaid invoices." It is also "only taken into account after invoices finalize."

In other words, an unpaid $2,000 invoice does not appear in the Customer’s balance at all. The balance is a small side ledger of credits and carry-forward amounts waiting to be applied to future invoices. Your open receivables live on the invoices themselves, and the customer balance is covered on its own in the write-up on Stripe customer balance in QuickBooks.

For customers billed in more than one currency, Stripe keeps the equivalent figures per currency in invoice_credit_balance, applying each one only to a finalized invoice in the same currency.

Metadata and customer-configured Accounts

Two newer or less obvious parts of the object are worth knowing before you build on them.

metadata is a "Set of key-value pairs that you can attach to an object", useful "for storing additional information about the object in a structured format." It is yours: Stripe stores it, and other systems read it only if they have specifically been built to. Putting a clean company name or an internal account number into metadata does not make any downstream tool use it.

customer_account is "The ID of an Account representing a customer", which Stripe says you can use "with any v1 API that accepts a customer_account parameter." It reflects Stripe’s newer model, in which a single Account object can represent a customer. If your integration is being rebuilt around that model, check how each downstream system identifies the payer before you switch, because a tool that expects a cus_ ID may not follow.