API reference

Test mode. Use your secret key on your server; live processing is currently disabled.

https://api.knoxapi.com

Send form-encoded requests with Authorization: Bearer sk_test_....

Complete OpenAPI specification · Integration guide

Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.

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.

Request parameters

Parameter	Location	Type	Description
`collection_method`	query	string	The collection method of the invoice to retrieve. Either `charge_automatically` or `send_invoice`.
`created`	query	one of multiple schemas	Only return invoices that were created during the given date interval.
`customer`	query	string	Only return invoices for the customer specified by this customer ID.
`customer_account`	query	string	Only return invoices for the account representing the customer specified by this account ID.
`due_date`	query	one of multiple schemas
`ending_before`	query	string	A 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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A 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.
`status`	query	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`subscription`	query	string	Only return invoices for the subscription specified by this subscription ID.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of invoice
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices

Create an invoice

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.

Request parameters

Field	Type	Description
`account_tax_ids`	one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`application_fee_amount`	integer	A fee in cents (or local equivalent) that will be applied to the invoice and transferred to the application owner's Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee. For more information, see the application fees [documentation](https://docs.stripe.com/billing/invoices/connect#collecting-fees).
`auto_advance`	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action. Defaults to false.
`automatic_tax`	object	Settings for automatic tax lookup for this invoice.
`automatically_finalizes_at`	integer	The time when this invoice should be scheduled to finalize (up to 5 years in the future). The invoice is finalized at this time if it's still in draft state.
`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. Defaults to `charge_automatically`.
`currency`	string	The currency to create this invoice in. Defaults to that of `customer` if not specified.
`custom_fields`	one of multiple schemas	A list of up to 4 custom fields to be displayed on the invoice.
`customer`	string	The ID of the customer to bill.
`customer_account`	string	The ID of the account to bill.
`days_until_due`	integer	The number of days from when the invoice is created until it is due. Valid only for invoices where `collection_method=send_invoice`.
`default_payment_method`	string	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	string	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates`	array of string	The tax rates that will apply to any line item that does not have `tax_rates` set.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts`	one of multiple schemas	The coupons and promotion codes to redeem into discounts for the invoice. If not specified, inherits the discount from the invoice's customer. Pass an empty string to avoid inheriting any discounts.
`due_date`	integer	The date on which payment for this invoice is due. Valid only for invoices where `collection_method=send_invoice`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`expand`	array of string	Specifies which fields in the response should be expanded.
`footer`	string	Footer to be displayed on the invoice.
`from_invoice`	object	Revise an existing invoice. The new invoice will be created in `status=draft`. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`issuer`	object	The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.
`number`	string	Set the number for this invoice. If no number is present then a number will be assigned automatically when the invoice is finalized. In many markets, regulations require invoices to be unique, sequential and / or gapless. You are responsible for ensuring this is true across all your different invoicing systems in the event that you edit the invoice number using our API. If you use only Stripe for your invoices and do not change invoice numbers, Stripe handles this aspect of compliance for you automatically.
`on_behalf_of`	string	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`payment_settings`	object	Configuration settings for the PaymentIntent that is generated when the invoice is finalized.
`pending_invoice_items_behavior`	string	How to handle pending invoice items on invoice creation. Defaults to `exclude` if the parameter is omitted.
`rendering`	object	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	object	Settings for the cost of shipping for this invoice.
`shipping_details`	object	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`statement_descriptor`	string	Extra information about a charge for the customer's credit card statement. It must contain at least one letter. If not specified and this invoice is part of a subscription, the default `statement_descriptor` will be set to the first subscription item's product's `statement_descriptor`.
`subscription`	string	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.
`transfer_data`	object	If specified, the funds from the invoice will be transferred to the destination and the ID of the resulting transfer will be found on the invoice's charge.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/create_preview

Create a preview invoice

At any time, you can preview the upcoming invoice for a subscription or subscription schedule. 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. You can also preview the effects of creating or updating a subscription or subscription schedule, including a preview of any prorations that will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed on the invoice is to consider line items where parent.subscription_item_details.proration is true. 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. 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

Request parameters

Field	Type	Description
`automatic_tax`	object	Settings for automatic tax lookup for this invoice preview.
`currency`	string	The currency to preview this invoice in. Defaults to that of `customer` if not specified.
`customer`	string	The identifier of the customer whose upcoming invoice you're retrieving. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set.
`customer_account`	string	The identifier of the account representing the customer whose upcoming invoice you're retrieving. If `automatic_tax` is enabled then one of `customer`, `customer_account`, `customer_details`, `subscription`, or `schedule` must be set.
`customer_details`	object	Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set.
`discounts`	one of multiple schemas	The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts.
`expand`	array of string	Specifies which fields in the response should be expanded.
`invoice_items`	array of object	List of invoice items to add or update in the upcoming invoice preview (up to 250).
`issuer`	object	The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`preview_mode`	string	Customizes the types of values to include when calculating the invoice. Defaults to `next` if unspecified.
`schedule`	string	The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields.
`schedule_details`	object	The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields.
`subscription`	string	The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a `subscription_details.items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_details.items` is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions.
`subscription_details`	object	The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/invoices/search

Search invoices

Search for invoices you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`page`	query	string	A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
`query`	query	string	The search query string. See [search query language](https://docs.stripe.com/search#search-query-language) and the list of supported [query fields for invoices](https://docs.stripe.com/search#query-fields-for-invoices).

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of invoice
`has_more` required	boolean
`next_page`	string
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`total_count`	integer	The total number of objects that match the query, only accurate up to 10,000.
`url` required	string

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/invoices/{invoice}

Delete a draft invoice

Permanently deletes a one-off invoice draft. This cannot be undone. Attempts to delete invoices that are no longer in a draft state will fail; once an invoice has been finalized or if an invoice is for a subscription, it must be voided.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`deleted` required	boolean	Always true for a deleted object
`id` required	string	Unique identifier for the object.
`object` required	string	String representing the object's type. Objects of the same type share the same value.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/invoices/{invoice}

Retrieve an invoice

Retrieves the invoice with the given ID.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`invoice`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}

Update an invoice

Draft invoices are fully editable. Once an invoice is finalized, monetary values, as well as collection_method, 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_advance=false.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`account_tax_ids`	one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`application_fee_amount`	integer	A fee in cents (or local equivalent) that will be applied to the invoice and transferred to the application owner's Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee. For more information, see the application fees [documentation](https://docs.stripe.com/billing/invoices/connect#collecting-fees).
`auto_advance`	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice.
`automatic_tax`	object	Settings for automatic tax lookup for this invoice.
`automatically_finalizes_at`	integer	The time when this invoice should be scheduled to finalize (up to 5 years in the future). The invoice is finalized at this time if it's still in draft state. To turn off automatic finalization, set `auto_advance` to false.
`collection_method`	string	Either `charge_automatically` or `send_invoice`. This field can be updated only on `draft` invoices.
`custom_fields`	one of multiple schemas	A list of up to 4 custom fields to be displayed on the invoice. If a value for `custom_fields` is specified, the list specified will replace the existing custom field list on this invoice. Pass an empty string to remove previously-defined fields.
`days_until_due`	integer	The number of days from which the invoice is created until it is due. Only valid for invoices where `collection_method=send_invoice`. This field can only be updated on `draft` invoices.
`default_payment_method`	string	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates`	one of multiple schemas	The tax rates that will apply to any line item that does not have `tax_rates` set. Pass an empty string to remove previously-defined tax rates.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts`	one of multiple schemas	The discounts that will apply to the invoice. Pass an empty string to remove previously-defined discounts.
`due_date`	integer	The date on which payment for this invoice is due. Only valid for invoices where `collection_method=send_invoice`. This field can only be updated on `draft` invoices.
`effective_at`	one of multiple schemas	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`expand`	array of string	Specifies which fields in the response should be expanded.
`footer`	string	Footer to be displayed on the invoice.
`issuer`	object	The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.
`number`	one of multiple schemas	Set the number for this invoice. If no number is present then a number will be assigned automatically when the invoice is finalized. In many markets, regulations require invoices to be unique, sequential and / or gapless. You are responsible for ensuring this is true across all your different invoicing systems in the event that you edit the invoice number using our API. If you use only Stripe for your invoices and do not change invoice numbers, Stripe handles this aspect of compliance for you automatically.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`payment_settings`	object	Configuration settings for the PaymentIntent that is generated when the invoice is finalized.
`rendering`	object	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	Settings for the cost of shipping for this invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`statement_descriptor`	string	Extra information about a charge for the customer's credit card statement. It must contain at least one letter. If not specified and this invoice is part of a subscription, the default `statement_descriptor` will be set to the first subscription item's product's `statement_descriptor`.
`transfer_data`	one of multiple schemas	If specified, the funds from the invoice will be transferred to the destination and the ID of the resulting transfer will be found on the invoice's charge. This will be unset if you POST an empty value.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/add_lines

Bulk add invoice line items

Adds multiple line items to an invoice. This is only possible when an invoice is still a draft.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`invoice_metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.
`lines` required	array of object	The line items to add.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/attach_payment

Attach a payment to an Invoice

Attaches a PaymentIntent or an Out of Band Payment to the invoice, adding it to the list of payments. For the PaymentIntent, when the PaymentIntent’s status changes to succeeded, the payment is credited to the invoice, increasing its amount_paid. When the invoice is fully paid, the invoice’s status becomes paid. If the PaymentIntent’s status is already succeeded when it’s attached, it’s credited to the invoice immediately. See: Partial payments to learn more.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`payment_intent`	string	The ID of the PaymentIntent to attach to the invoice.
`payment_record`	string	The ID of the PaymentRecord to attach to the invoice.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/finalize

Finalize an invoice

Stripe automatically finalizes drafts before sending and attempting payment on invoices. However, if you’d like to finalize a draft invoice manually, you can do so using this method.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`auto_advance`	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/invoices/{invoice}/lines

Retrieve an invoice's line items

When retrieving an invoice, you’ll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Request parameters

Parameter	Location	Type	Description
`ending_before`	query	string	A 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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`invoice`	path	string
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A 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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of line_item	Details about each object.
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/mark_uncollectible

Mark an invoice as uncollectible

Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/pay

Pay an invoice

Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your subscriptions settings. However, if you’d like to attempt payment on an invoice out of the normal collection schedule or for some other reason, you can do so.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`forgive`	boolean	In cases where the source used to pay the invoice has insufficient funds, passing `forgive=true` controls whether a charge should be attempted for the full amount available on the source, up to the amount to fully pay the invoice. This effectively forgives the difference between the amount available on the source and the amount due. Passing `forgive=false` will fail the charge if the source hasn't been pre-funded with the right amount. An example for this case is with ACH Credit Transfers and wires: if the amount wired is less than the amount due by a small amount, you might want to forgive the difference. Defaults to `false`.
`mandate`	one of multiple schemas	ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the payment_method param or the invoice's default_payment_method or default_source, if set.
`off_session`	boolean	Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `true` (off-session).
`paid_out_of_band`	boolean	Boolean representing whether an invoice is paid outside of Stripe. This will result in no charge being made. Defaults to `false`.
`payment_method`	string	A PaymentMethod to be charged. The PaymentMethod must be the ID of a PaymentMethod belonging to the customer associated with the invoice being paid.
`source`	string	A payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/remove_lines

Bulk remove invoice line items

Removes multiple line items from an invoice. This is only possible when an invoice is still a draft.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`invoice_metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.
`lines` required	array of object	The line items to remove.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/send

Send an invoice for manual payment

Stripe will automatically send invoices to customers according to your subscriptions settings. However, if you’d like to manually send an invoice to your customer out of the normal schedule, you can do so. When sending invoices that have already been paid, there will be no reference to the payment in the email. Requests made in test-mode result in no emails being sent, despite sending an invoice.sent event.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/update_lines

Bulk update invoice line items

Updates multiple line items on an invoice. This is only possible when an invoice is still a draft.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`invoice_metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`. For [type=subscription](https://docs.stripe.com/api/invoices/line_item#invoice_line_item_object-type) line items, the incoming metadata specified on the request is directly used to set this value, in contrast to [type=invoiceitem](api/invoices/line_item#invoice_line_item_object-type) line items, where any existing metadata on the invoice line is merged with the incoming data.
`lines` required	array of object	The line items to update.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/void

Void an invoice

Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to deletion, however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found. Consult with local regulations to determine whether and how an invoice might be amended, canceled, or voided in the jurisdiction you’re doing business in. You might need to issue another invoice or credit note instead. Stripe recommends that you consult with your legal counsel for advice specific to your business.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`account_country`	string	The country of the business associated with this invoice, most often the business creating the invoice.
`account_name`	string	The public name of the business associated with this invoice, most often the business creating the invoice.
`account_tax_ids`	array of one of multiple schemas	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
`amount_due` required	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` required	integer	Amount that was overpaid on the invoice. The amount overpaid is credited to the customer's credit balance.
`amount_paid` required	integer	The amount, in cents (or local equivalent), that was paid.
`amount_paid_off_stripe` required	integer	Amount, in cents (or local equivalent), that was paid on the invoice outside of Stripe.
`amount_remaining` required	integer	The difference between amount_due and amount_paid, in cents (or local equivalent).
`amount_shipping` required	integer	This is the sum of all the shipping amounts.
`application`	one of multiple schemas	ID of the Connect Application that created the invoice.
`attempt_count` required	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` required	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` required	boolean	Controls whether Stripe performs [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action.
`automatic_tax` required	automatic_tax
`automatically_finalizes_at`	integer	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_reason`	string	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` required	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_secret`	one of multiple schemas	The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`custom_fields`	array of invoice_setting_custom_field	Custom fields displayed on the invoice.
`customer` required	one of multiple schemas	The ID of the customer to bill.
`customer_account`	string	The ID of the account representing the customer to bill.
`customer_address`	one of multiple schemas	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_email`	string	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_name`	string	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_phone`	string	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_shipping`	one of multiple schemas	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_exempt`	string	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_ids`	array of 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.
`default_payment_method`	one of multiple schemas	ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
`default_source`	one of multiple schemas	ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
`default_tax_rates` required	array of tax_rate	The tax rates applied to this invoice, if any.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`due_date`	integer	The date on which payment for this invoice is due. This value will be `null` for invoices where `collection_method=charge_automatically`.
`effective_at`	integer	The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.
`ending_balance`	integer	Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
`footer`	string	Footer displayed on the invoice.
`from_invoice`	one of multiple schemas	Details of the invoice that was cloned. See the [revision documentation](https://docs.stripe.com/invoicing/invoice-revisions) for more details.
`hosted_invoice_url`	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.
`id` required	string	Unique identifier for the object. For preview invoices created using the [create preview](https://stripe.com/docs/api/invoices/create_preview) endpoint, this id will be prefixed with `upcoming_in`.
`invoice_pdf`	string	The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
`issuer` required	connect_account_reference
`last_finalization_error`	one of multiple schemas	The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
`latest_revision`	one of multiple schemas	The ID of the most recent non-draft revision of this invoice
`lines` required	object	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.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_payment_attempt`	integer	The time at which payment will next be attempted. This value will be `null` for invoices where `collection_method=send_invoice`.
`number`	string	A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer's unique invoice_prefix if it is specified.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect) documentation for details.
`parent`	one of multiple schemas	The parent that generated this invoice
`payment_settings` required	invoices_payment_settings
`payments`	object	Payments for this invoice. Use [invoice payment](/api/invoice-payment) to get more details.
`period_end` required	integer	The latest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`period_start` required	integer	The earliest timestamp at which invoice items can be associated with this invoice. Use the [line item period](/api/invoices/line_item#invoice_line_item_object-period) to get the service period for each price.
`post_payment_credit_notes_amount` required	integer	Total amount of all post-payment credit notes issued for this invoice.
`pre_payment_credit_notes_amount` required	integer	Total amount of all pre-payment credit notes issued for this invoice.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this invoice.
`rendering`	one of multiple schemas	The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
`shipping_cost`	one of multiple schemas	The details of the cost of shipping, including the ShippingRate applied on the invoice.
`shipping_details`	one of multiple schemas	Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer.
`starting_balance` required	integer	Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
`statement_descriptor`	string	Extra information about an invoice for the customer's credit card statement.
`status`	string	The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://docs.stripe.com/billing/invoices/workflow#workflow-overview)
`status_transitions` required	invoices_resource_status_transitions
`subtotal` required	integer	Total of all subscriptions, invoice items, and prorations on the invoice before any invoice level discount or exclusive tax is applied. Item discounts are already incorporated
`subtotal_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
`test_clock`	one of multiple schemas	ID of the test clock this invoice belongs to.
`threshold_reason`	invoice_threshold_reason
`total` required	integer	Total after discounts and taxes.
`total_discount_amounts`	array of discounts_resource_discount_amount	The aggregate amounts calculated per discount across all line items.
`total_excluding_tax`	integer	The integer amount in cents (or local equivalent) representing the total amount of the invoice including all discounts but excluding all tax.
`total_pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.
`total_taxes`	array of billing_bill_resource_invoicing_taxes_tax	The aggregate tax information of all line items.
`webhooks_delivered_at`	integer	Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have [been exhausted](https://docs.stripe.com/billing/webhooks#understand). This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/invoices/{invoice}/lines/{line_item_id}

Update an invoice's line item

Updates an invoice’s line item. Some fields, such as tax_amounts, only live on the invoice line item, so they can only be updated through this endpoint. Other fields, such as amount, live on both the invoice item and the invoice line item, so updates on this endpoint will propagate to the invoice item as well. Updating an invoice’s line item is only possible before the invoice is finalized.

Request parameters

Parameter	Location	Type	Description
`invoice`	path	string	Invoice ID of line item
`line_item_id`	path	string	Invoice line item ID

Field	Type	Description
`amount`	integer	The integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount.
`description`	string	An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.
`discountable`	boolean	Controls whether discounts apply to this line item. Defaults to false for prorations or negative line items, and true for all other line items. Cannot be set to true for prorations.
`discounts`	one of multiple schemas	The coupons, promotion codes & existing discounts which apply to the line item. Item discounts are applied before invoice discounts. Pass an empty string to remove previously-defined discounts.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`. For [type=subscription](/api/invoices/line_item) line items, the incoming metadata specified on the request is directly used to set this value, in contrast to [type=invoiceitem](/api/invoices/line_item) line items, where any existing metadata on the invoice line is merged with the incoming data.
`period`	object	The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://docs.stripe.com/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://docs.stripe.com/revenue-recognition/methodology/subscriptions-and-invoicing) for details.
`price_data`	object	Data used to generate a new [Price](https://docs.stripe.com/api/prices) object inline.
`pricing`	object	The pricing information for the invoice item.
`quantity`	integer	Non-negative integer. The quantity of units for the line item. Use `quantity_decimal` instead to provide decimal precision. This field will be deprecated in favor of `quantity_decimal` in a future version.
`quantity_decimal`	string	Non-negative decimal with at most 12 decimal places. The quantity of units for the line item.
`tax_amounts`	one of multiple schemas	A list of up to 20 tax amounts for this line item. This can be useful if you calculate taxes on your own or use a third-party to calculate them. You cannot set tax amounts if any line item has [tax_rates](https://docs.stripe.com/api/invoices/line_item#invoice_line_item_object-tax_rates) or if the invoice has [default_tax_rates](https://docs.stripe.com/api/invoices/object#invoice_object-default_tax_rates) or uses [automatic tax](https://docs.stripe.com/tax/invoicing). Pass an empty string to remove previously defined tax amounts.
`tax_rates`	one of multiple schemas	The tax rates which apply to the line item. When set, the `default_tax_rates` on the invoice do not apply to this line item. Pass an empty string to remove previously-defined tax rates.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	The amount, in cents (or local equivalent).
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`discount_amounts`	array of discounts_resource_discount_amount	The amount of discount calculated per discount for this line item.
`discountable` required	boolean	If true, discounts will apply to this line item. Always false for prorations.
`discounts` required	array of one of multiple schemas	The discounts applied to the invoice line item. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
`id` required	string	Unique identifier for the object.
`invoice`	string	The ID of the invoice that contains this line item.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Note that for line items with `type=subscription`, `metadata` reflects the current metadata from the subscription associated with the line item, unless the invoice line was directly updated with different metadata after creation.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`parent`	one of multiple schemas	The parent that generated this line item.
`period` required	invoice_line_item_period
`pretax_credit_amounts`	array of invoices_resource_pretax_credit_amount	Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this line item.
`pricing`	one of multiple schemas	The pricing information of the line item.
`quantity`	integer	Quantity of units for the invoice line item in integer format, with any decimal precision truncated. For the line item's full-precision decimal quantity, use `quantity_decimal`. This field will be deprecated in favor of `quantity_decimal` in a future version. If the line item is a proration or subscription, the quantity of the subscription that the proration was computed for.
`quantity_decimal`	string	Non-negative decimal with at most 12 decimal places. The quantity of units for the line item.
`subscription`	one of multiple schemas
`subtotal` required	integer	The subtotal of the line item, in cents (or local equivalent), before any discounts or taxes.
`taxes`	array of billing_bill_resource_invoicing_taxes_tax	The tax information of the line item.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors