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

Update an invoice

POST / v1 / invoices /:id

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.

Parameters

• auto _ advance boolean Controls whether Stripe performs automatic collection of the invoice.
• automatic _ tax object Settings for automatic tax lookup for this invoice.
• collection _ method enum Either charge_automatically or send_invoice. This field can be updated only on draft invoices. Possible enum values charge_automatically send_invoice
• 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.

More parameters

• account _ tax _ ids array of strings
• application _ fee _ amount integer Connect only
• automatically _ finalizes _ at timestamp
• 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
• issuer object Connect only
• number string
• on _ behalf _ of string Connect only
• payment _ settings object
• rendering object
• shipping _ cost object
• shipping _ details object
• statement _ descriptor string
• transfer _ data object Connect only

Returns

Returns the invoice object.

Response