Stripe: Bulk add invoice line items

← Invoices operations · Get started

Operation stripe.postinvoicesinvoiceaddlines

Provider route: POST /v1/invoices/{invoice}/add_lines. 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"]["postInvoicesInvoiceAddLines"]>[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.postInvoicesInvoiceAddLines(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_add_lines(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	Required within parent	Additional keys: not allowed
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.invoice_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.invoice_metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.invoice_metadata (anyOf 1).*	string	Additional keys
body.invoice_metadata (anyOf 2)	string	Alternative	One of:
body.lines	array	Required within parent	The line items to add.
body.lines[]	object	Each item
body.lines[].amount	integer	Optional
body.lines[].description	string	Optional	Maximum length: 5000
body.lines[].discountable	boolean	Optional
body.lines[].discounts	JSON	Optional
body.lines[].discounts (anyOf 1)	array	Alternative
body.lines[].discounts (anyOf 1)[]	object	Each item
body.lines[].discounts (anyOf 1)[].coupon	string	Optional	Maximum length: 5000
body.lines[].discounts (anyOf 1)[].discount	string	Optional	Maximum length: 5000
body.lines[].discounts (anyOf 1)[].promotion_code	string	Optional	Maximum length: 5000
body.lines[].discounts (anyOf 2)	string	Alternative	One of:
body.lines[].invoice_item	string	Optional	Maximum length: 5000
body.lines[].metadata	JSON	Optional
body.lines[].metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.lines[].metadata (anyOf 1).*	string	Additional keys
body.lines[].metadata (anyOf 2)	string	Alternative	One of:
body.lines[].period	object	Optional
body.lines[].period.end	integer	Required within parent	Format: unix-time
body.lines[].period.start	integer	Required within parent	Format: unix-time
body.lines[].price_data	Model	Optional	Expand Bulk add invoice line items — request body — body lines item price data
body.lines[].pricing	object	Optional
body.lines[].pricing.price	string	Optional	Maximum length: 5000
body.lines[].quantity	integer	Optional
body.lines[].quantity_decimal	string	Optional	Format: decimal
body.lines[].tax_amounts	JSON	Optional
body.lines[].tax_amounts (anyOf 1)	array	Alternative
body.lines[].tax_amounts (anyOf 1)[]	Model	Each item	Expand Update an invoice’s line item — request body — body tax amounts array item
body.lines[].tax_amounts (anyOf 2)	string	Alternative	One of:
body.lines[].tax_rates	JSON	Optional
body.lines[].tax_rates (anyOf 1)	array	Alternative
body.lines[].tax_rates (anyOf 1)[]	string	Each item	Maximum length: 5000
body.lines[].tax_rates (anyOf 2)	string	Alternative	One of:

Referenced models: Bulk add invoice line items — request body — body lines item price data, Update an invoice’s line item — request body — body tax amounts array 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

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

Bulk add invoice line items — request body — body lines item price data

Field	Type	Presence	Description and constraints
$	object	Root
currency	string	Required within parent	Format: currency
product	string	Optional	Maximum length: 5000
product_data	Model	Optional	Expand Update an invoice's line item — request body — body price data product data
tax_behavior	string	Optional	One of: exclusive, inclusive, unspecified
unit_amount	integer	Optional
unit_amount_decimal	string	Optional	Format: decimal

Referenced models: Update an invoice's line item — request body — body price data product data

Update an invoice's line item — request body — body tax amounts array item

Field	Type	Presence	Description and constraints
$	object	Root
amount	integer	Required within parent
tax_rate_data	Model	Required within parent	Expand Update an invoice's line item — request body — body tax amounts array item tax rate data
taxability_reason	string	Optional	One of: customer_exempt, not_collecting, not_subject_to_tax, not_supported, portion_product_exempt, portion_reduced_rated, portion_standard_rated, product_exempt, product_exempt_holiday, proportionally_rated, reduced_rated, reverse_charge, standard_rated, taxable_basis_reduced, zero_rated
taxable_amount	integer	Required within parent

Referenced models: Update an invoice's line item — request body — body tax amounts array item tax 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 — automatic tax

Field	Type	Presence	Description and constraints
$	object	Root
disabled_reason	JSON	Optional
disabled_reason (anyOf 1)	string	Alternative	If Stripe disabled automatic tax, this enum describes why. Known values: finalization_requires_location_inputs, finalization_system_error
disabled_reason (anyOf 2)	null	Alternative
enabled	boolean	Required within parent	Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://docs.stripe.com/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices.
liability	JSON	Optional
liability (anyOf 1)	JSON	Alternative	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.
liability (anyOf 1) (anyOf 1)	Model	Alternative	Expand Pay an invoice — response body — issuer
liability (anyOf 2)	null	Alternative
provider	JSON	Optional
provider (anyOf 1)	string	Alternative	The tax provider powering automatic tax. Maximum length: 5000
provider (anyOf 2)	null	Alternative
status	JSON	Optional
status (anyOf 1)	string	Alternative	The status of the most recent automated tax calculation for this invoice. Known values: complete, failed, requires_location_inputs
status (anyOf 2)	null	Alternative

Referenced models: Pay an invoice — response body — issuer

Pay an invoice — response body — parent / The parent that generated this invoice / type: quote details, subscription details quote details value quote

Field	Type	Presence	Description and constraints
$	object	Root
quote	string	Required within parent	The quote that generated this invoice Maximum length: 5000

Policy, approvals and errors

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