The Invoice object

Attributes

id string Unique identifier for the object. For preview invoices created using the create preview endpoint, this id will be prefixed with upcoming_in.
auto _ advance boolean Controls whether Stripe performs automatic collection of the invoice. If false, the invoice’s state doesn’t automatically advance without an explicit action.
automatic _ tax object Settings and latest results for automatic tax lookup for this invoice.
collection _ method enum 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. Possible enum values charge_automatically Attempt payment using the default source attached to the customer. send_invoice Email payment instructions to the customer.
confirmation _ secret nullable object Includable The confirmation secret associated with this invoice. Currently, this contains the client_secret of the PaymentIntent that Stripe creates during invoice finalization.
currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer string Expandable The ID of the customer to bill.
customer _ account nullable string The ID of the account representing the customer to bill.
description nullable string An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
hosted _ invoice _ url nullable 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.
lines 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.
metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
parent nullable object The parent that generated this invoice
payments object Includable Payments for this invoice. Use invoice payment to get more details.
period _ end timestamp The latest timestamp at which invoice items can be associated with this invoice. Use the line item period to get the service period for each price.
period _ start timestamp The earliest timestamp at which invoice items can be associated with this invoice. Use the line item period to get the service period for each price.
status nullable enum The status of the invoice, one of draft, open, paid, uncollectible, or void. Learn more
total integer Total after discounts and taxes.

More attributes

object string, value is "invoice"
account _ country nullable string
account _ name nullable string
account _ tax _ ids nullable array of strings Expandable
amount _ due integer
amount _ overpaid integer
amount _ paid integer
amount _ paid _ off _ stripe integer Includable
amount _ remaining integer
amount _ shipping integer
application nullable string Expandable Connect only
attempt _ count integer
attempted boolean
automatically _ finalizes _ at nullable timestamp
billing _ reason nullable enum
created timestamp
custom _ fields nullable array of objects
customer _ address nullable object
customer _ email nullable string
customer _ name nullable string
customer _ phone nullable string
customer _ shipping nullable object
customer _ tax _ exempt nullable enum
customer _ tax _ ids nullable array of objects
default _ payment _ method nullable string Expandable
default _ source nullable string Expandable
default _ tax _ rates array of objects
discounts array of strings Expandable
due _ date nullable timestamp
effective _ at nullable timestamp
ending _ balance nullable integer
footer nullable string
from _ invoice nullable object
invoice _ pdf nullable string
issuer object Connect only
last _ finalization _ error nullable object
latest _ revision nullable string Expandable
livemode boolean
next _ payment _ attempt nullable timestamp
number nullable string
on _ behalf _ of nullable string Expandable Connect only
payment _ settings object
post _ payment _ credit _ notes _ amount integer
pre _ payment _ credit _ notes _ amount integer
receipt _ number nullable string
rendering nullable object
shipping _ cost nullable object
shipping _ details nullable object
starting _ balance integer
statement _ descriptor nullable string
status _ details nullable object
status _ transitions object
subtotal integer
subtotal _ excluding _ tax nullable integer
test _ clock nullable string Expandable
threshold _ reason nullable object
total _ discount _ amounts nullable array of objects
total _ excluding _ tax nullable integer
total _ pretax _ credit _ amounts nullable array of objects
total _ taxes nullable array of objects
webhooks _ delivered _ at nullable timestamp

The Invoice object

Create a preview invoice

POST / v1 / invoices / create_preview

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

Parameters

automatic _ tax object Settings for automatic tax lookup for this invoice preview.
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.
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.

More parameters

currency enum
customer _ details object
discounts array of objects
invoice _ items array of objects
issuer object Connect only
on _ behalf _ of string Connect only
preview _ mode enum
schedule string
schedule _ details object
subscription _ details object

Returns

Returns an invoice if valid customer information is provided. Raises an error otherwise.

Response

Create an invoice

POST / v1 / invoices

This endpoint creates a draft invoice for a given customer. The invoice remains a draft until you finalize the invoice, which allows you to pay or send the invoice to your customers.

Parameters

auto _ advance boolean Controls whether Stripe performs automatic 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.
collection _ method enum 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. Possible enum values charge_automatically send_invoice
customer string Required unless from_invoice is provided The ID of the customer to bill.
customer _ account string The ID of the account to bill.
description string An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
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.

More parameters

account _ tax _ ids array of strings
application _ fee _ amount integer Connect only
automatically _ finalizes _ at timestamp
currency enum
custom _ fields array of objects
days _ until _ due integer
default _ payment _ method string
default _ source string
default _ tax _ rates array of strings
discounts array of objects
due _ date timestamp
effective _ at timestamp
footer string
from _ invoice object Required unless customer is provided
issuer object Connect only
number string
on _ behalf _ of string Connect only
payment _ settings object
pending _ invoice _ items _ behavior enum
rendering object
shipping _ cost object
shipping _ details object
statement _ descriptor string
transfer _ data object Connect only

Returns

Returns the invoice object. Raises an error if the customer ID provided is invalid.

Response