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.

Parameters

• auto_advanceboolean

  Controls whether Stripe performs automatic collection of the invoice. If false, the invoice’s state doesn’t automatically advance without an explicit action. Defaults to false.

• automatic_taxobject

  Settings for automatic tax lookup for this invoice.

  Hide child parameters

  • automatic_tax.enabledbooleanRequired

    Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified tax rates, negative amounts, or tax_behavior=unspecified) cannot be added to automatic tax invoices.

  • automatic_tax.liabilityobjectConnect only

    The account that’s liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account.

    Hide child parameters

    • automatic_tax.liability.typeenumRequired

      Type of the account referenced in the request.

      Possible enum values

      account Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

      self Indicates that the account being referenced is the account making the API request.

    • automatic_tax.liability.accountstringRequired only if type is account

      The connected account being referenced when type is account.

• collection_methodenum

  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

• customerstringRequired unless from_invoice is provided

  The ID of the customer who will be billed.

• descriptionstring

  An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.

• metadataobject

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

• subscriptionstring

  The ID of the subscription to invoice, if any. If set, the created invoice will only include pending invoice items for that subscription. The subscription’s billing cycle and regular subscription events won’t be affected.

More parameters

Collapse all

• account_tax_idsarray of strings

  The account tax IDs associated with the invoice. Only editable when the invoice is a draft.

• application_fee_amountintegerConnect only

  A fee in cents 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.

• automatically_finalizes_attimestamp

  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.

• currencyenum

  The currency to create this invoice in. Defaults to that of customer if not specified.

• custom_fieldsarray of objects

  A list of up to 4 custom fields to be displayed on the invoice.

  Hide child parameters

  • custom_fields.namestringRequired

    The name of the custom field. This may be up to 40 characters.

  • custom_fields.valuestringRequired

    The value of the custom field. This may be up to 140 characters.

• days_until_dueinteger

  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_methodstring

  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_sourcestring

  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_ratesarray of strings

  The tax rates that will apply to any line item that does not have tax_rates set.

• discountsarray of objects

  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.

  Hide child parameters

  • discounts.couponstring

    ID of the coupon to create a new discount for.

  • discounts.discountstring

    ID of an existing discount on the object (or one of its ancestors) to reuse.

  • discounts.promotion_codestring

    ID of the promotion code to create a new discount for.

• due_datetimestamp

  The date on which payment for this invoice is due. Valid only for invoices where collection_method=send_invoice.

• effective_attimestamp

  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.

• footerstring

  Footer to be displayed on the invoice.

• from_invoiceobjectRequired unless customer is provided

  Revise an existing invoice. The new invoice will be created in status=draft. See the revision documentation for more details.

  Hide child parameters

  • from_invoice.actionstringRequired

    The relation between the new invoice and the original invoice. Currently, only ‘revision’ is permitted

  • from_invoice.invoicestringRequired

    The id of the invoice that will be cloned.

• issuerobjectConnect only

  The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

  Hide child parameters

  • issuer.typeenumRequired

    Type of the account referenced in the request.

    Possible enum values

    account Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

    self Indicates that the account being referenced is the account making the API request.

  • issuer.accountstringRequired only if type is account

    The connected account being referenced when type is account.

• numberstring

  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_ofstringConnect only

  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 documentation for details.

• payment_settingsobject

  Configuration settings for the PaymentIntent that is generated when the invoice is finalized.

  Hide child parameters

  • payment_settings.default_mandatestring

    ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the invoice’s default_payment_method or default_source, if set.

  • payment_settings.payment_method_optionsobject

    Payment-method-specific configuration to provide to the invoice’s PaymentIntent.

    Hide child parameters

    • payment_settings.payment_method_options.acss_debitobject

      If paying by acss_debit, this sub-hash contains details about the Canadian pre-authorized debit payment method options to pass to the invoice’s PaymentIntent.

      Hide child parameters

      • payment_settings.payment_method_options.acss_debit.mandate_optionsobject

        Additional fields for Mandate creation

        Hide child parameters

        • payment_settings.payment_method_options.acss_debit.mandate_options.transaction_typeenum

          Transaction type of the mandate.

          Possible enum values

          business Transactions are made for business reasons

          personal Transactions are made for personal reasons

      • payment_settings.payment_method_options.acss_debit.verification_methodenum

        Verification method for the intent

        Possible enum values

        automatic Instant verification with fallback to microdeposits.

        instant Instant verification.

        microdeposits Verification using microdeposits.

    • payment_settings.payment_method_options.bancontactobject

      If paying by bancontact, this sub-hash contains details about the Bancontact payment method options to pass to the invoice’s PaymentIntent.

      Hide child parameters

      • payment_settings.payment_method_options.bancontact.preferred_languageenum

        Preferred language of the Bancontact authorization page that the customer is redirected to.

        Possible enum values

        de German

        en English

        fr French

        nl Dutch

    • payment_settings.payment_method_options.cardobject

      If paying by card, this sub-hash contains details about the Card payment method options to pass to the invoice’s PaymentIntent.

      Hide child parameters

      • payment_settings.payment_method_options.card.installmentsobject

        Installment configuration for payments attempted on this invoice.

        For more information, see the installments integration guide.

        Hide child parameters

        • payment_settings.payment_method_options.card.installments.enabledboolean

          Setting to true enables installments for this invoice. Setting to false will prevent any selected plan from applying to a payment.

        • payment_settings.payment_method_options.card.installments.planobject

          The selected installment plan to use for this invoice.

          Hide child parameters

          • payment_settings.payment_method_options.card.installments.plan.typeenumRequired

            Type of installment plan, one of fixed_count, bonus, or revolving.

            Possible enum values

            bonus An installment plan used in Japan, where the customer defers payment to a later date that aligns with their salary bonus.

            fixed_count An installment plan where the number of installment payments is fixed and known at the time of purchase.

            revolving An installment plan used in Japan, where the customer pays a certain amount each month, and the remaining balance rolls over to the next month.

          • payment_settings.payment_method_options.card.installments.plan.countinteger

            For fixed_count installment plans, this is required. It represents the number of installment payments your customer will make to their credit card.

          • payment_settings.payment_method_options.card.installments.plan.intervalenum

            For fixed_count installment plans, this is required. It represents the interval between installment payments your customer will make to their credit card. One of month.

            Possible enum values

            month

      • payment_settings.payment_method_options.card.request_three_d_secureenumadvanced

        We strongly recommend that you rely on our SCA Engine to automatically prompt your customers for authentication based on risk level and other requirements. However, if you wish to request 3D Secure based on logic from your own fraud engine, provide this option. Read our guide on manually requesting 3D Secure for more information on how this configuration interacts with Radar and our SCA Engine.

        Possible enum values

        any Use any to manually request 3DS with a preference for a frictionless flow, increasing the likelihood of the authentication being completed without any additional input from the customer. 3DS will always be attempted if it is supported for the card, but Stripe can’t guarantee your preference because the issuer determines the ultimate authentication flow. To learn more about 3DS flows, read our guide.

        automatic (Default) Our SCA Engine automatically prompts your customers for authentication based on risk level and other requirements.

        challenge Use challenge to request 3DS with a preference for a challenge flow, where the customer must respond to a prompt for active authentication. Stripe can’t guarantee your preference because the issuer determines the ultimate authentication flow. To learn more about 3DS flows, read our guide.

    • payment_settings.payment_method_options.customer_balanceobject

      If paying by customer_balance, this sub-hash contains details about the Bank transfer payment method options to pass to the invoice’s PaymentIntent.

      Hide child parameters

      • payment_settings.payment_method_options.customer_balance.bank_transferobject

        Configuration for the bank transfer funding type, if the funding_type is set to bank_transfer.

        Hide child parameters

        • payment_settings.payment_method_options.customer_balance.bank_transfer.eu_bank_transferobjectRequired if type=eu_bank_transfer

          Configuration for eu_bank_transfer funding type.

          Hide child parameters

          • payment_settings.payment_method_options.customer_balance.bank_transfer.eu_bank_transfer.countrystringRequired

            The desired country code of the bank account information. Permitted values include: BE, DE, ES, FR, IE, or NL.

        • payment_settings.payment_method_options.customer_balance.bank_transfer.typeenum

          The bank transfer type that can be used for funding. Permitted values include: eu_bank_transfer, gb_bank_transfer, jp_bank_transfer, mx_bank_transfer, or us_bank_transfer.

      • payment_settings.payment_method_options.customer_balance.funding_typeenum

        The funding method type to be used when there are not enough funds in the customer balance. Permitted values include: bank_transfer.

    • payment_settings.payment_method_options.konbiniobject

      If paying by konbini, this sub-hash contains details about the Konbini payment method options to pass to the invoice’s PaymentIntent.

    • payment_settings.payment_method_options.sepa_debitobject

      If paying by sepa_debit, this sub-hash contains details about the SEPA Direct Debit payment method options to pass to the invoice’s PaymentIntent.

    • payment_settings.payment_method_options.us_bank_accountobject

      If paying by us_bank_account, this sub-hash contains details about the ACH direct debit payment method options to pass to the invoice’s PaymentIntent.

      Hide child parameters

      • payment_settings.payment_method_options.us_bank_account.financial_connectionsobject

        Additional fields for Financial Connections Session creation

        Hide child parameters

        • payment_settings.payment_method_options.us_bank_account.financial_connections.filtersobject

          Provide filters for the linked accounts that the customer can select for the payment method.

          Hide child parameters

          • payment_settings.payment_method_options.us_bank_account.financial_connections.filters.account_subcategoriesarray of enums

            The account subcategories to use to filter for selectable accounts. Valid subcategories are checking and savings.

            Possible enum values

            checking Bank account subcategory is checking

            savings Bank account subcategory is savings

        • payment_settings.payment_method_options.us_bank_account.financial_connections.permissionsarray of strings

          The list of permissions to request. If this parameter is passed, the payment_method permission must be included. Valid permissions include: balances, ownership, payment_method, and transactions.

        • payment_settings.payment_method_options.us_bank_account.financial_connections.prefetcharray of enums

          List of data features that you would like to retrieve upon account creation.

          Possible enum values

          balances Requests to prefetch balance data on accounts collected in this session.

          ownership Requests to prefetch ownership data on accounts collected in this session.

          transactions Requests to prefetch transaction data on accounts collected in this session.

      • payment_settings.payment_method_options.us_bank_account.verification_methodenum

        Verification method for the intent

        Possible enum values

        automatic Instant verification with fallback to microdeposits.

        instant Instant verification only.

        microdeposits Verification using microdeposits. Cannot be used with Stripe Checkout, Hosted Invoices, or Payment Element.

  • payment_settings.payment_method_typesarray of enums

    The list of payment method types (e.g. card) to provide to the invoice’s PaymentIntent. If not set, Stripe attempts to automatically determine the types to use by looking at the invoice’s default payment method, the subscription’s default payment method, the customer’s default payment method, and your invoice template settings. Should not be specified with payment_method_configuration

    Possible enum values

    ach_debit ACH

    acss_debit Canadian pre-authorized debit

    affirm Affirm If set, the Subscription collection_method must be send_invoice.

    amazon_pay Amazon Pay

    au_becs_debit BECS Direct Debit

    bacs_debit Bacs Direct Debit

    bancontact Bancontact If set, the Subscription collection_method must be send_invoice.

    boleto Boleto

    card Card

    cashapp Cash App Pay

    Show 26 more

• pending_invoice_items_behaviorenum

  How to handle pending invoice items on invoice creation. Defaults to exclude if the parameter is omitted.

  Possible enum values

  exclude Always create an empty invoice draft regardless if there are pending invoice items or not.

  include Include any pending invoice items, and create an empty draft invoice if no pending invoice items exist.

• renderingobject

  The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.

  Hide child parameters

  • rendering.amount_tax_displayenum

    How line-item prices and amounts will be displayed with respect to tax on invoice PDFs. One of exclude_tax or include_inclusive_tax. include_inclusive_tax will include inclusive tax (and exclude exclusive tax) in invoice PDF amounts. exclude_tax will exclude all tax (inclusive and exclusive alike) from invoice PDF amounts.

    Possible enum values

    exclude_tax

    include_inclusive_tax

  • rendering.pdfobject

    Invoice pdf rendering options

    Hide child parameters

    • rendering.pdf.page_sizeenum

      Page size for invoice PDF. Can be set to a4, letter, or auto. If set to auto, invoice PDF page size defaults to a4 for customers with Japanese locale and letter for customers with other locales.

      Possible enum values

      a4

      auto

      letter

  • rendering.templatestring

    ID of the invoice rendering template to use for this invoice.

  • rendering.template_versioninteger

    The specific version of invoice rendering template to use for this invoice.

• shipping_costobject

  Settings for the cost of shipping for this invoice.

  Hide child parameters

  • shipping_cost.shipping_ratestringRequired unless shipping_rate_data is provided

    The ID of the shipping rate to use for this order.

  • shipping_cost.shipping_rate_dataobjectRequired unless shipping_rate is provided

    Parameters to create a new ad-hoc shipping rate for this order.

    Hide child parameters

    • shipping_cost.shipping_rate_data.display_namestringRequired

      The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions.

    • shipping_cost.shipping_rate_data.delivery_estimateobject

      The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions.

      Hide child parameters

      • shipping_cost.shipping_rate_data.delivery_estimate.maximumobject

        The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.

        Hide child parameters

        • shipping_cost.shipping_rate_data.delivery_estimate.maximum.unitenumRequired

          A unit of time.

          Possible enum values

          business_day The delivery estimate is in business days.

          day The delivery estimate is in days.

          hour The delivery estimate is in hours.

          month The delivery estimate is in months.

          week The delivery estimate is in weeks.

        • shipping_cost.shipping_rate_data.delivery_estimate.maximum.valueintegerRequired

          Must be greater than 0.

      • shipping_cost.shipping_rate_data.delivery_estimate.minimumobject

        The lower bound of the estimated range. If empty, represents no lower bound.

        Hide child parameters

        • shipping_cost.shipping_rate_data.delivery_estimate.minimum.unitenumRequired

          A unit of time.

          Possible enum values

          business_day The delivery estimate is in business days.

          day The delivery estimate is in days.

          hour The delivery estimate is in hours.

          month The delivery estimate is in months.

          week The delivery estimate is in weeks.

        • shipping_cost.shipping_rate_data.delivery_estimate.minimum.valueintegerRequired

          Must be greater than 0.

    • shipping_cost.shipping_rate_data.fixed_amountobject

      Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.

      Hide child parameters

      • shipping_cost.shipping_rate_data.fixed_amount.amountintegerRequired

        A non-negative integer in cents representing how much to charge.

      • shipping_cost.shipping_rate_data.fixed_amount.currencyenumRequired

        Three-letter ISO currency code, in lowercase. Must be a supported currency.

      • shipping_cost.shipping_rate_data.fixed_amount.currency_optionsobject

        Shipping rates defined in each available currency option. Each key must be a three-letter ISO currency code and a supported currency.

        Hide child parameters

        • shipping_cost.shipping_rate_data.fixed_amount.currency_options.<currency>.amountintegerRequired

          A non-negative integer in cents representing how much to charge.

        • shipping_cost.shipping_rate_data.fixed_amount.currency_options.<currency>.tax_behaviorenumRecommended if calculating taxes

          Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified.

          Possible enum values

          exclusive

          inclusive

          unspecified

    • shipping_cost.shipping_rate_data.metadataobject

      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

    • shipping_cost.shipping_rate_data.tax_behaviorenumRecommended if calculating taxes

      Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified.

      Possible enum values

      exclusive

      inclusive

      unspecified

    • shipping_cost.shipping_rate_data.tax_codestringRecommended if calculating taxes

      A tax code ID. The Shipping tax code is txcd_92010001.

    • shipping_cost.shipping_rate_data.typeenumRequired

      The type of calculation to use on the shipping rate.

      Possible enum values

      fixed_amount The shipping rate is a fixed amount.

• shipping_detailsobject

  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.

  Hide child parameters

  • shipping_details.addressobjectRequired

    Shipping address

    Hide child parameters

    • shipping_details.address.citystring

      City, district, suburb, town, or village.

    • shipping_details.address.countrystringRequired for calculating taxes

      Two-letter country code (ISO 3166-1 alpha-2).

    • shipping_details.address.line1string

      Address line 1 (e.g., street, PO Box, or company name).

    • shipping_details.address.line2string

      Address line 2 (e.g., apartment, suite, unit, or building).

    • shipping_details.address.postal_codestringRequired for calculating taxes

      ZIP or postal code.

    • shipping_details.address.statestring

      State, county, province, or region.

  • shipping_details.namestringRequired

    Recipient name.

  • shipping_details.phonestring

    Recipient phone (including extension)

• statement_descriptorstring

  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_dataobjectConnect only

  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.

  Hide child parameters

  • transfer_data.destinationstringRequired

    ID of an existing, connected Stripe account.

  • transfer_data.amountinteger

    The amount that will be transferred automatically when the invoice is paid. If no amount is set, the full amount is transferred.