Stripe: Create an invoice

← Invoices operations · Get started

Operation stripe.postinvoices

Provider route: POST /v1/invoices. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["invoices"]["postInvoices"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.invoices.postInvoices(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.invoices.post_invoices(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Optional	Additional keys: not allowed
body.account_tax_ids	JSON	Optional	The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
body.account_tax_ids (anyOf 1)	array	Alternative
body.account_tax_ids (anyOf 1)[]	string	Each item	Maximum length: 5000
body.account_tax_ids (anyOf 2)	string	Alternative	One of:
body.application_fee_amount	integer	Optional	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).
body.auto_advance	boolean	Optional	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.
body.automatic_tax	object	Optional	Settings for automatic tax lookup for this invoice.
body.automatic_tax.enabled	boolean	Required within parent
body.automatic_tax.liability	object	Optional
body.automatic_tax.liability.account	string	Optional
body.automatic_tax.liability.type	string	Required within parent	One of: account, self
body.automatically_finalizes_at	integer	Optional	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. Format: unix-time
body.collection_method	string	Optional	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`. One of: charge_automatically, send_invoice
body.currency	string	Optional	The currency to create this invoice in. Defaults to that of `customer` if not specified. Format: currency
body.custom_fields	JSON	Optional	A list of up to 4 custom fields to be displayed on the invoice.
body.custom_fields (anyOf 1)	array	Alternative
body.custom_fields (anyOf 1)[]	object	Each item
body.custom_fields (anyOf 1)[].name	string	Required within parent	Maximum length: 40
body.custom_fields (anyOf 1)[].value	string	Required within parent	Maximum length: 140
body.custom_fields (anyOf 2)	string	Alternative	One of:
body.customer	string	Optional	The ID of the customer to bill. Maximum length: 5000
body.customer_account	string	Optional	The ID of the account to bill. Maximum length: 5000
body.days_until_due	integer	Optional	The number of days from when the invoice is created until it is due. Valid only for invoices where `collection_method=send_invoice`.
body.default_payment_method	string	Optional	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. Maximum length: 5000
body.default_source	string	Optional	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. Maximum length: 5000
body.default_tax_rates	array	Optional	The tax rates that will apply to any line item that does not have `tax_rates` set.
body.default_tax_rates[]	string	Each item	Maximum length: 5000
body.description	string	Optional	An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard. Maximum length: 1500
body.discounts	JSON	Optional	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.
body.discounts (anyOf 1)	array	Alternative
body.discounts (anyOf 1)[]	object	Each item
body.discounts (anyOf 1)[].coupon	string	Optional	Maximum length: 5000
body.discounts (anyOf 1)[].discount	string	Optional	Maximum length: 5000
body.discounts (anyOf 1)[].promotion_code	string	Optional	Maximum length: 5000
body.discounts (anyOf 2)	string	Alternative	One of:
body.due_date	integer	Optional	The date on which payment for this invoice is due. Valid only for invoices where `collection_method=send_invoice`. Format: unix-time
body.effective_at	integer	Optional	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. Format: unix-time
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.footer	string	Optional	Footer to be displayed on the invoice. Maximum length: 5000
body.from_invoice	object	Optional	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.
body.from_invoice.action	string	Required within parent	One of: revision Maximum length: 5000
body.from_invoice.invoice	string	Required within parent	Maximum length: 5000
body.issuer	object	Optional	The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
body.issuer.account	string	Optional
body.issuer.type	string	Required within parent	One of: account, self
body.metadata	JSON	Optional	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`.
body.metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.metadata (anyOf 1).*	string	Additional keys
body.metadata (anyOf 2)	string	Alternative	One of:
body.number	string	Optional	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. Maximum length: 26
body.on_behalf_of	string	Optional	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.
body.payment_settings	Model	Optional	Expand Create an invoice — request body — body payment settings
body.pending_invoice_items_behavior	string	Optional	How to handle pending invoice items on invoice creation. Defaults to `exclude` if the parameter is omitted. One of: exclude, include
body.rendering	Model	Optional	Expand Create an invoice — request body — body rendering
body.shipping_cost	object	Optional	Settings for the cost of shipping for this invoice.
body.shipping_cost.shipping_rate	string	Optional	Maximum length: 5000
body.shipping_cost.shipping_rate_data	Model	Optional	Expand Create an invoice — request body — body shipping cost shipping rate data
body.shipping_details	object	Optional	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.
body.shipping_details.address	object	Required within parent
body.shipping_details.address.city	string	Optional	Maximum length: 5000
body.shipping_details.address.country	string	Optional	Maximum length: 5000
body.shipping_details.address.line1	string	Optional	Maximum length: 5000
body.shipping_details.address.line2	string	Optional	Maximum length: 5000
body.shipping_details.address.postal_code	string	Optional	Maximum length: 5000
body.shipping_details.address.state	string	Optional	Maximum length: 5000
body.shipping_details.name	string	Required within parent	Maximum length: 5000
body.shipping_details.phone	JSON	Optional
body.shipping_details.phone (anyOf 1)	string	Alternative	Maximum length: 5000
body.shipping_details.phone (anyOf 2)	string	Alternative	One of:
body.statement_descriptor	string	Optional	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`. Maximum length: 22
body.subscription	string	Optional	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. Maximum length: 5000
body.transfer_data	object	Optional	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.
body.transfer_data.amount	integer	Optional
body.transfer_data.destination	string	Required within parent

Referenced models: Create an invoice — request body — body payment settings, Create an invoice — request body — body rendering, Create an invoice — request body — body shipping cost shipping rate data

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Pay an invoice — response body

Referenced models: Pay an invoice — response body

Schemas

710 more schemas are linked from the tables above, on the schema pages.

Create an invoice — request body — body payment settings

Field	Type	Presence	Description and constraints
$	object	Root	Configuration settings for the PaymentIntent that is generated when the invoice is finalized.
default_mandate	JSON	Optional
default_mandate (anyOf 1)	string	Alternative	Maximum length: 5000
default_mandate (anyOf 2)	string	Alternative	One of:
payment_method_options	Model	Optional	Expand Create an invoice — request body — body payment settings payment method options
payment_method_types	JSON	Optional
payment_method_types (anyOf 1)	array	Alternative
payment_method_types (anyOf 1)[]	string	Each item	One of: ach_credit_transfer, ach_debit, acss_debit, affirm, alipay, amazon_pay, au_becs_debit, bacs_debit, bancontact, billie, blik, boleto, card, cashapp, crypto, custom, customer_balance, eps, fpx, giropay, grabpay, ideal, jp_credit_transfer, kakao_pay, klarna, konbini, kr_card, link, mb_way, multibanco, naver_pay, nz_bank_account, p24, pay_by_bank, payco, paynow, paypal, payto, pix, promptpay, revolut_pay, satispay, sepa_credit_transfer, sepa_debit, sofort, swish, twint, upi, us_bank_account, wechat_pay
payment_method_types (anyOf 2)	string	Alternative	One of:

Referenced models: Create an invoice — request body — body payment settings payment method options

Create an invoice — request body — body rendering

Field	Type	Presence	Description and constraints
$	object	Root	The rendering-related settings that control how invoices render in customer-facing interfaces such as the PDF or hosted invoice page.
amount_tax_display	string	Optional	One of: , exclude_tax, include_inclusive_tax
pdf	object	Optional
pdf.page_size	string	Optional	One of: a4, auto, letter
template	string	Optional	Maximum length: 5000
template_version	JSON	Optional
template_version (anyOf 1)	integer	Alternative
template_version (anyOf 2)	string	Alternative	One of:

Create an invoice — request body — body shipping cost shipping rate data

Field	Type	Presence	Description and constraints
$	object	Root
delivery_estimate	object	Optional
delivery_estimate.maximum	object	Optional
delivery_estimate.maximum.unit	string	Required within parent	One of: business_day, day, hour, month, week
delivery_estimate.maximum.value	integer	Required within parent
delivery_estimate.minimum	object	Optional
delivery_estimate.minimum.unit	string	Required within parent	One of: business_day, day, hour, month, week
delivery_estimate.minimum.value	integer	Required within parent
display_name	string	Required within parent	Maximum length: 100
fixed_amount	object	Optional
fixed_amount.amount	integer	Required within parent
fixed_amount.currency	string	Required within parent	Format: currency
fixed_amount.currency_options	object	Optional	Additional keys: see wildcard field
fixed_amount.currency_options.*	object	Additional keys
fixed_amount.currency_options.*.amount	integer	Required within parent
fixed_amount.currency_options.*.tax_behavior	string	Optional	One of: exclusive, inclusive, unspecified
metadata	object	Optional	Additional keys: see wildcard field
metadata.*	string	Additional keys
tax_behavior	string	Optional	One of: exclusive, inclusive, unspecified
tax_code	string	Optional
type	string	Optional	One of: fixed_amount

Create a Location — response body — address

Field	Type	Presence	Description and constraints
$	object	Root
city	JSON	Optional
city (anyOf 1)	string	Alternative	City, district, suburb, town, or village. Maximum length: 5000
city (anyOf 2)	null	Alternative
country	JSON	Optional
country (anyOf 1)	string	Alternative	Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Maximum length: 5000
country (anyOf 2)	null	Alternative
line1	JSON	Optional
line1 (anyOf 1)	string	Alternative	Address line 1, such as the street, PO Box, or company name. Maximum length: 5000
line1 (anyOf 2)	null	Alternative
line2	JSON	Optional
line2 (anyOf 1)	string	Alternative	Address line 2, such as the apartment, suite, unit, or building. Maximum length: 5000
line2 (anyOf 2)	null	Alternative
postal_code	JSON	Optional
postal_code (anyOf 1)	string	Alternative	ZIP or postal code. Maximum length: 5000
postal_code (anyOf 2)	null	Alternative
state	JSON	Optional
state (anyOf 1)	string	Alternative	State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). Maximum length: 5000
state (anyOf 2)	null	Alternative

Cancel a SetupIntent — response body — last_setup_error / value / type: api error, card error, idempotency error, invalid request error

Field	Type	Presence	Description and constraints
$	object	Root
advice_code	string	Optional	For card errors resulting from a card issuer decline, a short string indicating [how to proceed with an error](https://docs.stripe.com/declines/card#retrying-issuer-declines) if they provide one. Maximum length: 5000
charge	string	Optional	For card errors, the ID of the failed charge. Maximum length: 5000
code	string	Optional	For some errors that could be handled programmatically, a short string indicating the [error code](https://docs.stripe.com/error-codes) reported. Maximum length: 5000
decline_code	string	Optional	For card errors resulting from a card issuer decline, a short string indicating the [card issuer's reason for the decline](https://docs.stripe.com/declines#issuer-declines) if they provide one. Maximum length: 5000
doc_url	string	Optional	A URL to more information about the [error code](https://docs.stripe.com/error-codes) reported. Maximum length: 5000
message	string	Optional	A human-readable message providing more details about the error. For card errors, these messages can be shown to your users. Maximum length: 40000
network_advice_code	string	Optional	For card errors resulting from a card issuer decline, a 2 digit code which indicates the advice given to merchant by the card network on how to proceed with an error. Maximum length: 5000
network_decline_code	string	Optional	For payments declined by the network, an alphanumeric code which indicates the reason the payment failed. Maximum length: 5000
param	string	Optional	If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field. Maximum length: 5000
payment_intent	Model	Optional	Expand Cancel a Payment Intent — response body
payment_method	Model	Optional	Expand Create a Payment Method — response body
payment_method_type	string	Optional	If the error is specific to the type of payment method, the payment method type that had a problem. This field is only populated for invoice-related errors. Maximum length: 5000
request_log_url	string	Optional	A URL to the request log entry in your dashboard. Maximum length: 5000
setup_intent	Model	Optional	Expand Cancel a Setup Intent — response body
source	JSON	Optional	The [source object](https://docs.stripe.com/api/sources/object) for errors returned on a request involving a source.
source (anyOf 1)	Model	Alternative	Expand Retrieve a bank account — response body
source (anyOf 2)	Model	Alternative	Expand Retrieve a card — customers get Customers Customer Cards Id — response body
source (anyOf 3)	Model	Alternative	Expand Create a source — response body
type	string	Required within parent	The type of error returned. One of `api_error`, `card_error`, `idempotency_error`, or `invalid_request_error` Known values: api_error, card_error, idempotency_error, invalid_request_error

Referenced models: Retrieve a bank account — response body, Retrieve a card — customers get Customers Customer Cards Id — response body, Cancel a Payment Intent — response body, Create a Payment Method — response body, Cancel a Setup Intent — response body, Create a source — response body

PostApplicationFeesIdRefund — response body — application / object: application

Field	Type	Presence	Description and constraints
$	object	Root
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the application. Maximum length: 5000
name (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: application

Policy, approvals and errors

SDK function policy ID: stripe.postinvoices. Catalog operation: PostInvoices. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source