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_
advance booleanControls whether Stripe performs automatic collection of the invoice. If
false
, the invoice’s state doesn’t automatically advance without an explicit action. - automatic_
tax objectSettings and latest results for automatic tax lookup for this invoice.
- chargenullable stringExpandable
ID of the latest charge generated for this invoice, if any.
- collection_
method enumEither
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_ nullable stringurl 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_
intent nullable stringExpandableThe 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_
end timestampEnd 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_
start timestampStart 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_
country nullable string - account_
name nullable string - account_
tax_ nullable array of stringsExpandableids - amount_
due integer - amount_
paid integer - amount_
remaining integer - amount_
shipping integer - applicationnullable stringExpandableConnect only
- application_
fee_ nullable integerConnect onlyamount - attempt_
count integer - attemptedboolean
- automatically_
finalizes_ nullable timestampat - billing_
reason nullable enum - createdtimestamp
- custom_
fields nullable array of objects - customer_
address nullable object - customer_
email nullable string - customer_
name nullable string - customer_
phone nullable string - customer_
shipping nullable object - customer_
tax_ nullable enumexempt - customer_
tax_ nullable array of objectsids - default_
payment_ nullable stringExpandablemethod - default_
source nullable stringExpandable - default_
tax_ array of objectsrates - discountnullable objectDeprecated
- discountsarray of stringsExpandable
- due_
date nullable timestamp - effective_
at nullable timestamp - ending_
balance nullable integer - footernullable string
- from_
invoice nullable object - invoice_
pdf nullable string - issuerobjectConnect only
- last_
finalization_ nullable objecterror - latest_
revision nullable stringExpandable - livemodeboolean
- next_
payment_ nullable timestampattempt - numbernullable string
- on_
behalf_ nullable stringExpandableConnect onlyof - paidboolean
- paid_
out_ booleanof_ band - payment_
settings object - post_
payment_ integercredit_ notes_ amount - pre_
payment_ integercredit_ notes_ amount - quotenullable stringExpandable
- receipt_
number nullable string - renderingnullable object
- shipping_
cost nullable object - shipping_
details nullable object - starting_
balance integer - statement_
descriptor nullable string - status_
transitions object - subscription_
details nullable object - subscription_
proration_ nullable integerdate - subtotalinteger
- subtotal_
excluding_ nullable integertax - taxnullable integer
- test_
clock nullable stringExpandable - threshold_
reason nullable object - total_
discount_ nullable array of objectsamounts - total_
excluding_ nullable integertax - total_
pretax_ nullable array of objectscredit_ amounts - total_
tax_ array of objectsamounts - transfer_
data nullable objectConnect only - webhooks_
delivered_ nullable timestampat
{ "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_
advance booleanControls whether Stripe performs automatic collection of the invoice. If
false
, the invoice’s state doesn’t automatically advance without an explicit action. - automatic_
tax objectSettings for automatic tax lookup for this invoice.
- collection_
method enumEither
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 - customerstringRequired unless from_invoice is provided
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_ array of stringsids - application_
fee_ integerConnect onlyamount - automatically_
finalizes_ timestampat - currencyenum
- custom_
fields array of objects - days_
until_ integerdue - default_
payment_ stringmethod - default_
source string - default_
tax_ array of stringsrates - discountsarray of objects
- due_
date timestamp - effective_
at timestamp - footerstring
- from_
invoice objectRequired unless customer is provided - issuerobjectConnect only
- numberstring
- on_
behalf_ stringConnect onlyof - payment_
settings object - pending_
invoice_ enumitems_ behavior - renderingobject
- shipping_
cost object - shipping_
details object - statement_
descriptor string - transfer_
data objectConnect 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
- automatic_
tax objectSettings for automatic tax lookup for this invoice preview.
- 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
- couponstringDeprecated
- currencyenum
- customer_
details object - discountsarray of objects
- invoice_
items array of objects - issuerobjectConnect only
- on_
behalf_ stringConnect onlyof - preview_
mode enum - schedulestring
- schedule_
details object - subscription_
details object
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_
advance booleanControls whether Stripe performs automatic collection of the invoice.
- automatic_
tax objectSettings for automatic tax lookup for this invoice.
- collection_
method enumEither
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_ array of stringsids - application_
fee_ integerConnect onlyamount - automatically_
finalizes_ timestampat - custom_
fields array of objects - days_
until_ integerdue - default_
payment_ stringmethod - default_
source string - default_
tax_ array of stringsrates - discountsarray of objects
- due_
date timestamp - effective_
at timestamp - footerstring
- issuerobjectConnect only
- numberstring
- on_
behalf_ stringConnect onlyof - payment_
settings object - renderingobject
- shipping_
cost object - shipping_
details object - statement_
descriptor string - transfer_
data objectConnect 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}