Stripe: Update an invoice

← Invoices operations · Get started

Operation stripe.postinvoicesinvoice

Provider route: POST /v1/invoices/{invoice}. 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"]["postInvoicesInvoice"]>[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.postInvoicesInvoice(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_invoice(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.invoice	string	Required within parent	Maximum length: 5000
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.
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. To turn off automatic finalization, set `auto_advance` to false. Format: unix-time
body.collection_method	string	Optional	Either `charge_automatically` or `send_invoice`. This field can be updated only on `draft` invoices. One of: charge_automatically, send_invoice
body.custom_fields	JSON	Optional	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.
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.days_until_due	integer	Optional	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.
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	JSON	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.
body.default_source (anyOf 1)	string	Alternative	Maximum length: 5000
body.default_source (anyOf 2)	string	Alternative	One of:
body.default_tax_rates	JSON	Optional	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.
body.default_tax_rates (anyOf 1)	array	Alternative
body.default_tax_rates (anyOf 1)[]	string	Each item	Maximum length: 5000
body.default_tax_rates (anyOf 2)	string	Alternative	One of:
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 discounts that will apply to the invoice. Pass an empty string to remove previously-defined 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. Only valid for invoices where `collection_method=send_invoice`. This field can only be updated on `draft` invoices. Format: unix-time
body.effective_at	JSON	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.
body.effective_at (anyOf 1)	integer	Alternative	Format: unix-time
body.effective_at (anyOf 2)	string	Alternative	One of:
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.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	JSON	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.
body.number (anyOf 1)	string	Alternative	Maximum length: 26
body.number (anyOf 2)	string	Alternative	One of:
body.on_behalf_of	JSON	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.on_behalf_of (anyOf 1)	string	Alternative
body.on_behalf_of (anyOf 2)	string	Alternative	One of:
body.payment_settings	Model	Optional	Expand Create an invoice — request body — body payment settings
body.rendering	Model	Optional	Expand Create an invoice — request body — body rendering
body.shipping_cost	JSON	Optional	Settings for the cost of shipping for this invoice.
body.shipping_cost (anyOf 1)	Model	Alternative	Expand Create a Checkout Session — request body — body shipping options item
body.shipping_cost (anyOf 2)	string	Alternative	One of:
body.shipping_details	JSON	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 (anyOf 1)	object	Alternative
body.shipping_details (anyOf 1).address	object	Required within parent
body.shipping_details (anyOf 1).address.city	string	Optional	Maximum length: 5000
body.shipping_details (anyOf 1).address.country	string	Optional	Maximum length: 5000
body.shipping_details (anyOf 1).address.line1	string	Optional	Maximum length: 5000
body.shipping_details (anyOf 1).address.line2	string	Optional	Maximum length: 5000
body.shipping_details (anyOf 1).address.postal_code	string	Optional	Maximum length: 5000
body.shipping_details (anyOf 1).address.state	string	Optional	Maximum length: 5000
body.shipping_details (anyOf 1).name	string	Required within parent	Maximum length: 5000
body.shipping_details (anyOf 1).phone	JSON	Optional
body.shipping_details (anyOf 1).phone (anyOf 1)	string	Alternative	Maximum length: 5000
body.shipping_details (anyOf 1).phone (anyOf 2)	string	Alternative	One of:
body.shipping_details (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.transfer_data	JSON	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. This will be unset if you POST an empty value.
body.transfer_data (anyOf 1)	object	Alternative
body.transfer_data (anyOf 1).amount	integer	Optional
body.transfer_data (anyOf 1).destination	string	Required within parent
body.transfer_data (anyOf 2)	string	Alternative	One of:

Referenced models: Create an invoice — request body — body payment settings, Create an invoice — request body — body rendering, Create a Checkout Session — request body — body shipping options item

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

709 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 a Checkout Session — request body — body shipping options item

Field	Type	Presence	Description and constraints
$	object	Root
shipping_rate	string	Optional	Maximum length: 5000
shipping_rate_data	Model	Optional	Expand Create an invoice — request body — body shipping cost shipping rate data

Referenced models: Create an invoice — request body — body shipping cost shipping rate data

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

Pay an invoice — response body — issuer

Field	Type	Presence	Description and constraints
$	object	Root
account	JSON	Optional	The connected account being referenced when `type` is `account`.
account (anyOf 1)	string	Alternative	Maximum length: 5000
account (anyOf 2)	Model	Alternative	Expand Create an account — response body
type	string	Required within parent	Type of the account referenced. Known values: account, self

Referenced models: Create an account — response body

Pay an invoice — response body — custom fields Custom fields displayed on the invoice item

Field	Type	Presence	Description and constraints
$	object	Root
name	string	Required within parent	The name of the custom field. Maximum length: 5000
value	string	Required within parent	The value of the custom field. Maximum length: 5000

Policy, approvals and errors

SDK function policy ID: stripe.postinvoicesinvoice. Catalog operation: PostInvoicesInvoice. 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