Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.
They contain invoice items, and proration adjustments that may be caused by subscription upgrades/downgrades (if necessary).
If your invoice is configured to be billed through automatic charges, Stripe automatically finalizes your invoice and attempts payment. Note that finalizing the invoice, when automatic, does not happen immediately as the invoice is created. Stripe waits until one hour after the last webhook was successfully sent (or the last webhook timed out after failing). If you (and the platforms you may have connected to) have no webhooks configured, Stripe waits one hour after creation to finalize the invoice.
If your invoice is configured to be billed by sending an email, then based on your email settings, Stripe will email the invoice to your customer and await payment. These emails can contain a link to a hosted page to pay the invoice.
Stripe applies any customer credit on the account before determining the amount due for the invoice (i.e., the amount that will be actually charged). If the amount due for the invoice is less than Stripe’s minimum allowed charge per currency, the invoice is automatically marked paid, and we add the amount due to the customer’s credit balance which is applied to the next invoice.
More details on the customer’s credit balance are here.
Related guide: Send invoices to customers
- POST/
Attributes
- idstring
Unique identifier for the object. This property is always present unless the invoice is an upcoming invoice. See Retrieve an upcoming invoice for more details.
- auto_
advanceboolean Controls whether Stripe performs automatic collection of the invoice. If
false
, the invoice’s state doesn’t automatically advance without an explicit action. - chargenullable stringExpandable
ID of the latest charge generated for this invoice, if any.
- collection_
methodenum Either
charge_
, orautomatically send_
. 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.invoice Possible enum valuescharge_
automatically Attempt payment using the default source attached to the customer.
send_
invoice Email payment instructions to the customer.
- currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.
- customerstringExpandable
The ID of the customer who will be billed.
- descriptionnullable string
An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
- hosted_
invoice_ urlnullable string The URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.
- linesobject
The individual line items that make up the invoice.
lines
is sorted as follows: (1) pending invoice items (including prorations) in reverse chronological order, (2) subscription items in reverse chronological order, and (3) invoice items added after invoice creation in chronological order. - metadatanullable object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- payment_
intentnullable stringExpandable The PaymentIntent associated with this invoice. The PaymentIntent is generated when the invoice is finalized, and can then be used to pay the invoice. Note that voiding an invoice will cancel the PaymentIntent.
- period_
endtimestamp End of the usage period during which invoice items were added to this invoice. This looks back one period for a subscription invoice. Use the line item period to get the service period for each price.
- period_
starttimestamp Start of the usage period during which invoice items were added to this invoice. This looks back one period for a subscription invoice. Use the line item period to get the service period for each price.
- statusnullable enum
The status of the invoice, one of
draft
,open
,paid
,uncollectible
, orvoid
. Learn more - subscriptionnullable stringExpandable
The subscription that this invoice was prepared for, if any.
- totalinteger
Total after discounts and taxes.
More attributes
- objectstring
- account_
countrynullable string - account_
namenullable string - account_
tax_ idsnullable array of stringsExpandable - amount_
dueinteger - amount_
paidinteger - amount_
remaininginteger - amount_
shippinginteger - applicationnullable stringExpandableConnect only
- application_
fee_ amountnullable integerConnect only - attempt_
countinteger - attemptedboolean
- automatic_
taxobject - automatically_
finalizes_ atnullable timestamp - billing_
reasonnullable enum - createdtimestamp
- custom_
fieldsnullable array of objects - customer_
addressnullable object - customer_
emailnullable string - customer_
namenullable string - customer_
phonenullable string - customer_
shippingnullable object - customer_
tax_ exemptnullable enum - customer_
tax_ idsnullable array of objects - default_
payment_ methodnullable stringExpandable - default_
sourcenullable stringExpandable - default_
tax_ ratesarray of objects - discountnullable objectDeprecated
- discountsarray of stringsExpandable
- due_
datenullable timestamp - effective_
atnullable timestamp - ending_
balancenullable integer - footernullable string
- from_
invoicenullable object - invoice_
pdfnullable string - issuerobjectConnect only
- last_
finalization_ errornullable object - latest_
revisionnullable stringExpandable - livemodeboolean
- next_
payment_ attemptnullable timestamp - numbernullable string
- on_
behalf_ ofnullable stringExpandableConnect only - paidboolean
- paid_
out_ of_ bandboolean - payment_
settingsobject - post_
payment_ credit_ notes_ amountinteger - pre_
payment_ credit_ notes_ amountinteger - quotenullable stringExpandable
- receipt_
numbernullable string - renderingnullable object
- shipping_
costnullable object - shipping_
detailsnullable object - starting_
balanceinteger - statement_
descriptornullable string - status_
transitionsobject - subscription_
detailsnullable object - subscription_
proration_ datenullable integer - subtotalinteger
- subtotal_
excluding_ taxnullable integer - taxnullable integer
- test_
clocknullable stringExpandable - threshold_
reasonnullable object - total_
discount_ amountsnullable array of objects - total_
excluding_ taxnullable integer - total_
tax_ amountsarray of objects - transfer_
datanullable objectConnect only - webhooks_
delivered_ atnullable timestamp
{ "id": "in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 0, "amount_paid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "application_fee_amount": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_reason": "manual", "charge": null, "collection_method": "charge_automatically", "created": 1680644467, "currency": "usd", "custom_fields": null, "customer": "cus_NeZwdNtLEOXuvB", "customer_address": null, "customer_email": "jennyrosen@example.com", "customer_name": "Jenny Rosen", "customer_phone": null, "customer_shipping": null, "customer_tax_exempt": "none", "customer_tax_ids": [], "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discount": null, "discounts": [], "due_date": null, "ending_balance": null, "footer": null, "from_invoice": null, "hosted_invoice_url": null, "invoice_pdf": null, "issuer": { "type": "self" }, "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines" }, "livemode": false, "metadata": {}, "next_payment_attempt": null, "number": null, "on_behalf_of": null, "paid": false, "paid_out_of_band": false, "payment_intent": null, "payment_settings": { "default_mandate": null, "payment_method_options": null, "payment_method_types": null }, "period_end": 1680644467, "period_start": 1680644467, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "quote": null, "receipt_number": null, "rendering_options": null, "shipping_cost": null, "shipping_details": null, "starting_balance": 0, "statement_descriptor": null, "status": "draft", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": null, "subtotal": 0, "subtotal_excluding_tax": 0, "tax": null, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1680644467}
This endpoint creates a draft invoice for a given customer. The invoice remains a draft until you finalize the invoice, which allows you to pay or send the invoice to your customers.
Parameters
- auto_
advanceboolean Controls whether Stripe performs automatic collection of the invoice. If
false
, the invoice’s state doesn’t automatically advance without an explicit action. - collection_
methodenum Either
charge_
, orautomatically send_
. 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. Defaults toinvoice charge_
.automatically Possible enum valuescharge_
automatically send_
invoice - customerstring
The ID of the customer who will be billed.
- descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata
. - subscriptionstring
The ID of the subscription to invoice, if any. If set, the created invoice will only include pending invoice items for that subscription. The subscription’s billing cycle and regular subscription events won’t be affected.
More parameters
- account_
tax_ idsarray of strings - application_
fee_ amountintegerConnect only - automatic_
taxobject - currencyenum
- custom_
fieldsarray of objects - days_
until_ dueinteger - default_
payment_ methodstring - default_
sourcestring - default_
tax_ ratesarray of strings - discountsarray of objects
- due_
datetimestamp - effective_
attimestamp - footerstring
- from_
invoiceobject - issuerobjectConnect only
- numberstring
- on_
behalf_ ofstringConnect only - payment_
settingsobject - pending_
invoice_ items_ behaviorenum - renderingobject
- shipping_
costobject - shipping_
detailsobject - statement_
descriptorstring - transfer_
dataobjectConnect only
Returns
Returns the invoice object. Raises an error if the customer ID provided is invalid.
{ "id": "in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 0, "amount_paid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "application_fee_amount": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_reason": "manual", "charge": null, "collection_method": "charge_automatically", "created": 1680644467, "currency": "usd", "custom_fields": null, "customer": "cus_NeZwdNtLEOXuvB", "customer_address": null, "customer_email": "jennyrosen@example.com", "customer_name": "Jenny Rosen", "customer_phone": null, "customer_shipping": null, "customer_tax_exempt": "none", "customer_tax_ids": [], "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discount": null, "discounts": [], "due_date": null, "ending_balance": null, "footer": null, "from_invoice": null, "hosted_invoice_url": null, "invoice_pdf": null, "issuer": { "type": "self" }, "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines" }, "livemode": false, "metadata": {}, "next_payment_attempt": null, "number": null, "on_behalf_of": null, "paid": false, "paid_out_of_band": false, "payment_intent": null, "payment_settings": { "default_mandate": null, "payment_method_options": null, "payment_method_types": null }, "period_end": 1680644467, "period_start": 1680644467, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "quote": null, "receipt_number": null, "rendering_options": null, "shipping_cost": null, "shipping_details": null, "starting_balance": 0, "statement_descriptor": null, "status": "draft", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": null, "subtotal": 0, "subtotal_excluding_tax": 0, "tax": null, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1680644467}
At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice.
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.
You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_
parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start]
is equal to the subscription_
value passed in the request.
Note: Currency conversion calculations use the latest exchange rates. Exchange rates may vary between the time of the preview and the time of the actual invoice creation. Learn more
Parameters
- customerstring
The identifier of the customer whose upcoming invoice you’d like to retrieve. If
automatic_
is enabled then one oftax customer
,customer_
,details subscription
, orschedule
must be set. - subscriptionstring
The identifier of the subscription for which you’d like to retrieve the upcoming invoice. If not provided, but a
subscription_
is provided, you will preview creating a subscription with those items. If neitherdetails. items subscription
norsubscription_
is provided, you will retrieve the next upcoming invoice from among the customer’s subscriptions.details. items
More parameters
- automatic_
taxobject - couponstringDeprecated
- currencyenum
- customer_
detailsobject - discountsarray of objects
- invoice_
itemsarray of objects - issuerobjectConnect only
- on_
behalf_ ofstringConnect only - preview_
modeenum - schedulestring
- schedule_
detailsobject - subscription_
detailsobject
Returns
Returns an invoice if valid customer information is provided. Raises an error otherwise.
{ "id": "upcoming_in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 0, "amount_paid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "application_fee_amount": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "status": null }, "billing_reason": "manual", "charge": null, "collection_method": "charge_automatically", "created": 1680644467, "currency": "usd", "custom_fields": null, "customer": "cus_NeZwdNtLEOXuvB", "customer_address": null, "customer_email": "jennyrosen@example.com", "customer_name": "Jenny Rosen", "customer_phone": null, "customer_shipping": null, "customer_tax_exempt": "none", "customer_tax_ids": [], "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discount": null, "discounts": [], "due_date": null, "ending_balance": null, "footer": null, "from_invoice": null, "hosted_invoice_url": null, "invoice_pdf": null, "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines" }, "livemode": false, "metadata": {}, "next_payment_attempt": null, "number": null, "on_behalf_of": null, "paid": false, "paid_out_of_band": false, "payment_intent": null, "payment_settings": { "default_mandate": null, "payment_method_options": null, "payment_method_types": null }, "period_end": 1680644467, "period_start": 1680644467, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "quote": null, "receipt_number": null, "rendering_options": null, "shipping_cost": null, "shipping_details": null, "starting_balance": 0, "statement_descriptor": null, "status": "draft", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": null, "subtotal": 0, "subtotal_excluding_tax": 0, "tax": null, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1680644467}
Draft invoices are fully editable. Once an invoice is finalized, monetary values, as well as collection_
, become uneditable.
If you would like to stop the Stripe Billing engine from automatically finalizing, reattempting payments on, sending reminders for, or automatically reconciling invoices, pass auto_
.
Parameters
- auto_
advanceboolean Controls whether Stripe performs automatic collection of the invoice.
- collection_
methodenum Either
charge_
orautomatically send_
. This field can be updated only oninvoice draft
invoices.Possible enum valuescharge_
automatically send_
invoice - descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata
.
More parameters
- account_
tax_ idsarray of strings - application_
fee_ amountintegerConnect only - automatic_
taxobject - custom_
fieldsarray of objects - days_
until_ dueinteger - default_
payment_ methodstring - default_
sourcestring - default_
tax_ ratesarray of strings - discountsarray of objects
- due_
datetimestamp - effective_
attimestamp - footerstring
- issuerobjectConnect only
- numberstring
- on_
behalf_ ofstringConnect only - payment_
settingsobject - renderingobject
- shipping_
costobject - shipping_
detailsobject - statement_
descriptorstring - transfer_
dataobjectConnect only
Returns
Returns the invoice object.
{ "id": "in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 0, "amount_paid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "application_fee_amount": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_reason": "manual", "charge": null, "collection_method": "charge_automatically", "created": 1680644467, "currency": "usd", "custom_fields": null, "customer": "cus_NeZwdNtLEOXuvB", "customer_address": null, "customer_email": "jennyrosen@example.com", "customer_name": "Jenny Rosen", "customer_phone": null, "customer_shipping": null, "customer_tax_exempt": "none", "customer_tax_ids": [], "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discount": null, "discounts": [], "due_date": null, "ending_balance": null, "footer": null, "from_invoice": null, "hosted_invoice_url": null, "invoice_pdf": null, "issuer": { "type": "self" }, "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines" }, "livemode": false, "metadata": { "order_id": "6735" }, "next_payment_attempt": null, "number": null, "on_behalf_of": null, "paid": false, "paid_out_of_band": false, "payment_intent": null, "payment_settings": { "default_mandate": null, "payment_method_options": null, "payment_method_types": null }, "period_end": 1680644467, "period_start": 1680644467, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "quote": null, "receipt_number": null, "rendering_options": null, "shipping_cost": null, "shipping_details": null, "starting_balance": 0, "statement_descriptor": null, "status": "draft", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": null, "subtotal": 0, "subtotal_excluding_tax": 0, "tax": null, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1680644467}