← Invoices
get/v1/invoices

List all invoices

You can list all invoices, or list the invoices for a specific customer. The invoices are returned sorted by creation date, with the most recently created invoices appearing first.

Query parameters

NameDescription
collection_methodThe collection method of the invoice to retrieve. Either charge_automatically or send_invoice.
createdOnly return invoices that were created during the given date interval.
customerOnly return invoices for the customer specified by this customer ID.
customer_accountOnly return invoices for the account representing the customer specified by this account ID.
due_date
ending_beforeA cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
expandSpecifies which fields in the response should be expanded.
limitA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
starting_afterA cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
statusThe status of the invoice, one of draft, open, paid, uncollectible, or void. Learn more
subscriptionOnly return invoices for the subscription specified by this subscription ID.

Request body

object (no properties in spec)

Response

FieldTypeDescription
data*array<invoice>
array item fields
FieldTypeDescription
account_countrystring

The country of the business associated with this invoice, most often the business creating the invoice.

account_namestring

The public name of the business associated with this invoice, most often the business creating the invoice.

account_tax_idsarray<string | tax_id | deleted_tax_id>

The account tax IDs associated with the invoice. Only editable when the invoice is a draft.

amount_due*integer

Final amount due at this time for this invoice. If the invoice's total is smaller than the minimum charge amount, for example, or if there is account credit that can be applied to the invoice, the amount_due may be 0. If there is a positive starting_balance for the invoice (the customer owes money), the amount_due will also take that into account. The charge that gets generated for the invoice will be for the amount specified in amount_due.

amount_overpaid*integer

Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.

amount_paid*integer

The amount, in cents (or local equivalent), that was paid.

amount_paid_off_stripe*integer

Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.

amount_remaining*integer

The difference between amount_due and amount_paid, in cents (or local equivalent).

amount_shipping*integer

This is the sum of all the shipping amounts.

applicationstring | application | deleted_application

ID of the Connect Application that created the invoice.

attempt_count*integer

Number of payment attempts made for this invoice, from the perspective of the payment retry schedule. Any payment attempt counts as the first attempt, and subsequently only automatic retries increment the attempt count. In other words, manual payment attempts after the first attempt do not affect the retry schedule. If a failure is returned with a non-retryable return code, the invoice can no longer be retried unless a new payment method is obtained. Retries will continue to be scheduled, and attempt_count will continue to increment, but retries will only be executed if a new payment method is obtained.

attempted*boolean

Whether an attempt has been made to pay the invoice. An invoice is not attempted until 1 hour after the invoice.created webhook, for example, so you might not want to display that invoice as unpaid to your users.

auto_advance*boolean

Controls whether Stripe performs automatic collection of the invoice. If false, the invoice's state doesn't automatically advance without an explicit action.

automatic_tax*automatic_tax
5 nested fields
FieldTypeDescription
disabled_reasonstring

If Stripe disabled automatic tax, this enum describes why.

enabled*boolean

Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified tax rates, negative amounts, or tax_behavior=unspecified) cannot be added to automatic tax invoices.

liabilityconnect_account_reference

The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account.

providerstring

The tax provider powering automatic tax.

statusstring

The status of the most recent automated tax calculation for this invoice.

automatically_finalizes_atinteger (unix-time)

The time when this invoice is currently scheduled to be automatically finalized. The field will be null if the invoice is not scheduled to finalize in the future. If the invoice is not in the draft state, this field will always be null - see finalized_at for the time when an already-finalized invoice was finalized.

billing_reasonstring

Indicates the reason why the invoice was created. * manual: Unrelated to a subscription, for example, created via the invoice editor. * subscription: No longer in use. Applies to subscriptions from before May 2018 where no distinction was made between updates, cycles, and thresholds. * subscription_create: A new subscription was created. * subscription_cycle: A subscription advanced into a new period. * subscription_threshold: A subscription reached a billing threshold. * subscription_update: A subscription was updated. * upcoming: Reserved for upcoming invoices created through the Create Preview Invoice API or when an invoice.upcoming event is generated for an upcoming invoice on a subscription.

collection_method*string

Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this invoice using the default source attached to the customer. When sending an invoice, Stripe will email this invoice to the customer with payment instructions.

confirmation_secretinvoices_resource_confirmation_secret

The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.

created*integer (unix-time)

Time at which the object was created. Measured in seconds since the Unix epoch.

currency*string (currency)

Three-letter ISO currency code, in lowercase. Must be a supported currency.

custom_fieldsarray<invoice_setting_custom_field>

Custom fields displayed on the invoice.

array item fields
FieldTypeDescription
name*string

The name of the custom field.

value*string

The value of the custom field.

customer*string | customer | deleted_customer

The ID of the customer to bill.

customer_accountstring

The ID of the account representing the customer to bill.

customer_addressaddress

The customer's address. Until the invoice is finalized, this field will equal customer.address. Once the invoice is finalized, this field will no longer be updated.

customer_emailstring

The customer's email. Until the invoice is finalized, this field will equal customer.email. Once the invoice is finalized, this field will no longer be updated.

customer_namestring

The customer's name. Until the invoice is finalized, this field will equal customer.name. Once the invoice is finalized, this field will no longer be updated.

customer_phonestring

The customer's phone number. Until the invoice is finalized, this field will equal customer.phone. Once the invoice is finalized, this field will no longer be updated.

customer_shippingshipping

The customer's shipping information. Until the invoice is finalized, this field will equal customer.shipping. Once the invoice is finalized, this field will no longer be updated.

customer_tax_exemptstring

The customer's tax exempt status. Until the invoice is finalized, this field will equal customer.tax_exempt. Once the invoice is finalized, this field will no longer be updated.

customer_tax_idsarray<invoices_resource_invoice_tax_id>

The customer's tax IDs. Until the invoice is finalized, this field will contain the same tax IDs as customer.tax_ids. Once the invoice is finalized, this field will no longer be updated.

array item fields
FieldTypeDescription
type*string

The type of the tax ID, one of ad_nrt, ar_cuit, eu_vat, bo_tin, br_cnpj, br_cpf, cn_tin, co_nit, cr_tin, do_rcn, ec_ruc, eu_oss_vat, hr_oib, pe_ruc, ro_tin, rs_pib, sv_nit, uy_ruc, ve_rif, vn_tin, gb_vat, nz_gst, au_abn, au_arn, in_gst, no_vat, no_voec, za_vat, ch_vat, mx_rfc, sg_uen, ru_inn, ru_kpp, ca_bn, hk_br, es_cif, pl_nip, it_cf, fo_vat, gi_tin, py_ruc, tw_vat, th_vat, jp_cn, jp_rn, jp_trn, li_uid, li_vat, lk_vat, my_itn, us_ein, kr_brn, ca_qst, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, my_sst, sg_gst, ae_trn, cl_tin, sa_vat, id_npwp, my_frp, il_vat, ge_vat, ua_vat, is_vat, bg_uic, hu_tin, si_tin, ke_pin, tr_tin, eg_tin, ph_tin, al_tin, bh_vat, kz_bin, ng_tin, om_vat, de_stn, ch_uid, tz_vat, uz_vat, uz_tin, md_vat, ma_vat, by_tin, ao_tin, bs_tin, bb_tin, cd_nif, mr_nif, me_pib, zw_tin, ba_tin, gn_nif, mk_vat, sr_fin, sn_ninea, am_tin, np_pan, tj_tin, ug_tin, zm_tin, kh_tin, aw_tin, az_tin, bd_bin, bj_ifu, et_tin, kg_tin, la_tin, cm_niu, cv_nif, bf_ifu, or unknown

valuestring

The value of the tax ID.

has_more*boolean

True if this list has another page of items after this one that can be fetched.

object*string

String representing the object's type. Objects of the same type share the same value. Always has the value list.

url*string

The URL where this list can be accessed.