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 - automatically_
finalizes_ attimestamp - 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_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, orschedulemust 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 subscriptionnorsubscription_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_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 draftinvoices.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 - automatically_
finalizes_ attimestamp - 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_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}Retrieves the invoice with the given ID.
Parameters
No parameters.
Returns
Returns an invoice object if a valid invoice ID was provided. Raises an error otherwise.
The invoice object contains a lines hash that contains information about the subscriptions and invoice items that have been applied to the invoice, as well as any prorations that Stripe has automatically calculated. Each line on the invoice has an amount attribute that represents the amount actually contributed to the invoice’s total. For invoice items and prorations, the amount attribute is the same as for the invoice item or proration respectively. For subscriptions, the amount may be different from the plan’s regular price depending on whether the invoice covers a trial period or the invoice period differs from the plan’s usual interval.
The invoice object has both a subtotal and a total. The subtotal represents the total before any discounts, while the total is the final amount to be charged to the customer after all coupons have been applied.
The invoice also has a next_ attribute that tells you the next time (as a Unix timestamp) payment for the invoice will be automatically attempted. For invoices with manual payment collection, that have been closed, or that have reached the maximum number of retries (specified in your subscriptions settings), the next_ will be null.
{ "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_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, orschedulemust 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 subscriptionnorsubscription_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_
billing_ cycle_ anchorstring | timestampDeprecated - subscription_
cancel_ attimestampDeprecated - subscription_
cancel_ at_ period_ endbooleanDeprecated - subscription_
cancel_ nowbooleanDeprecated - subscription_
default_ tax_ ratesarray of stringsDeprecated - subscription_
detailsobject - subscription_
itemsarray of objectsDeprecated - subscription_
proration_ behaviorenumDeprecated - subscription_
proration_ datetimestampDeprecated - subscription_
resume_ atstringDeprecated - subscription_
start_ datetimestampDeprecated - subscription_
trial_ endstring | timestampDeprecated
Returns
Returns an invoice if valid customer information is provided. Raises an error otherwise.
{ "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_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}