Stripe: Create an invoice item

← Invoiceitems operations · Get started

Operation stripe.postinvoiceitems

Provider route: POST /v1/invoiceitems. 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["invoiceitems"]["postInvoiceitems"]>[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.invoiceitems.postInvoiceitems(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.invoiceitems.post_invoiceitems(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.amount	integer	Optional	The integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. Passing in a negative `amount` will reduce the `amount_due` on the invoice.
body.currency	string	Optional	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
body.customer	string	Optional	The ID of the customer to bill for this invoice item. Maximum length: 5000
body.customer_account	string	Optional	The ID of the account representing the customer to bill for this invoice item. Maximum length: 5000
body.description	string	Optional	An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. Maximum length: 5000
body.discountable	boolean	Optional	Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items.
body.discounts	JSON	Optional	The coupons and promotion codes to redeem into discounts for the invoice item or invoice line item.
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.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.invoice	string	Optional	The ID of an existing invoice to add this invoice item to. For subscription invoices, when left blank, the invoice item will be added to the next upcoming scheduled invoice. For standalone invoices, the invoice item won’t be automatically added unless you pass `pending_invoice_item_behavior: ‘include’` when creating the invoice. This is useful when adding invoice items in response to an invoice.created webhook. You can only add invoice items to draft invoices and there is a maximum of 250 items per invoice. Maximum length: 5000
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.period	Model	Optional	Expand Create an invoice item — request body — body period
body.price_data	object	Optional	Data used to generate a new [Price](https://docs.stripe.com/api/prices) object inline.
body.price_data.currency	string	Required within parent	Format: currency
body.price_data.product	string	Required within parent	Maximum length: 5000
body.price_data.tax_behavior	string	Optional	One of: exclusive, inclusive, unspecified
body.price_data.unit_amount	integer	Optional
body.price_data.unit_amount_decimal	string	Optional	Format: decimal
body.pricing	object	Optional	The pricing information for the invoice item.
body.pricing.price	string	Optional	Maximum length: 5000
body.quantity	integer	Optional	Non-negative integer. The quantity of units for the invoice item. Use `quantity_decimal` instead to provide decimal precision. This field will be deprecated in favor of `quantity_decimal` in a future version.
body.quantity_decimal	string	Optional	Non-negative decimal with at most 12 decimal places. The quantity of units for the invoice item. Format: decimal
body.subscription	string	Optional	The ID of a subscription to add this invoice item to. When left blank, the invoice item is added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription. Maximum length: 5000
body.tax_behavior	string	Optional	Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. One of: exclusive, inclusive, unspecified
body.tax_code	JSON	Optional	A [tax code](https://docs.stripe.com/tax/tax-categories) ID.
body.tax_code (anyOf 1)	string	Alternative
body.tax_code (anyOf 2)	string	Alternative	One of:
body.tax_rates	array	Optional	The tax rates which apply to the invoice item. When set, the `default_tax_rates` on the invoice do not apply to this invoice item.
body.tax_rates[]	string	Each item	Maximum length: 5000
body.unit_amount_decimal	string	Optional	The decimal unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This `unit_amount_decimal` will be multiplied by the quantity to get the full amount. Passing in a negative `unit_amount_decimal` will reduce the `amount_due` on the invoice. Accepts at most 12 decimal places. Format: decimal

Referenced models: Create an invoice item — request body — body period

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 Create an invoice item — response body

Referenced models: Create an invoice item — response body

Schemas

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

Create an invoice item — response body

Field	Type	Presence	Description and constraints
$	object	Root	Invoice Items represent the component lines of an [invoice](https://docs.stripe.com/api/invoices). When you create an invoice item with an `invoice` field, it is attached to the specified invoice and included as [an invoice line item](https://docs.stripe.com/api/invoices/line_item) within [invoice.lines](https://docs.stripe.com/api/invoices/object#invoice_object-lines). Invoice Items can be created before you are ready to actually send the invoice. This can be particularly useful when combined with a [subscription](https://docs.stripe.com/api/subscriptions). Sometimes you want to add a charge or credit to a customer, but actually charge or credit the customer's card only at the end of a regular billing cycle. This is useful for combining several charges (to minimize per-transaction fees), or for having Stripe tabulate your usage-based billing totals. Related guides: [Integrate with the Invoicing API](https://docs.stripe.com/invoicing/integration), [Subscription Invoices](https://docs.stripe.com/billing/invoices/subscription#adding-upcoming-invoice-items).
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	Amount (in the `currency` specified) of the invoice item. This should always be equal to `unit_amount * quantity`.
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
customer	JSON	Required within parent	The ID of the customer to bill for this invoice item.
customer (anyOf 1)	string	Alternative	Maximum length: 5000
customer (anyOf 2)	Model	Alternative	Expand Create a customer — response body
customer (anyOf 3)	Model	Alternative	Expand Delete a customer — response body
customer_account	JSON	Optional
customer_account (anyOf 1)	string	Alternative	The ID of the account to bill for this invoice item. Maximum length: 5000
customer_account (anyOf 2)	null	Alternative
date	JSON	Required within parent
date (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
date (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
description	JSON	Optional
description (anyOf 1)	string	Alternative	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000
description (anyOf 2)	null	Alternative
discountable	boolean	Required within parent	If true, discounts will apply to this invoice item. Always false for prorations.
discounts	JSON	Optional
discounts (anyOf 1)	array	Alternative	The discounts which apply to the invoice item. Item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
discounts (anyOf 1)[]	JSON	Each item
discounts (anyOf 1)[] (anyOf 1)	string	Alternative	Maximum length: 5000
discounts (anyOf 1)[] (anyOf 2)	Model	Alternative	Expand Get Customers Customer Discount — response body
discounts (anyOf 2)	null	Alternative
frozen_fields	array	Optional	Array of field names that can't be modified. Attempting to update a frozen field returns an error.
frozen_fields[]	string	Each item	Known values: discounts, pricing, quantity
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
invoice	JSON	Optional
invoice (anyOf 1)	JSON	Alternative	The ID of the invoice this invoice item belongs to.
invoice (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
invoice (anyOf 1) (anyOf 2)	Model	Alternative	Expand Pay an invoice — response body
invoice (anyOf 2)	null	Alternative
invoicing_rules	array	Optional	The rules that control when this invoice item is eligible for invoicing. All rules must be satisfied for the item to be invoiced.
invoicing_rules[]	Model	Each item	Expand Create an invoice item — response body — invoicing rules item
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadata	JSON	Optional
metadata (anyOf 1)	object	Alternative	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. Additional keys: see wildcard field
metadata (anyOf 1).*	string	Additional keys	Maximum length: 500
metadata (anyOf 2)	null	Alternative
net_amount	JSON	Optional
net_amount (anyOf 1)	integer	Alternative	The amount after discounts, but before credits and taxes. This field is `null` for `discountable=true` items.
net_amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: invoiceitem
parent	JSON	Optional
parent (anyOf 1)	JSON	Alternative	The parent that generated this invoice item.
parent (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create an invoice item — response body — parent / The parent that generated this invoice item / type: subscription details
parent (anyOf 2)	null	Alternative
period	Model	Required within parent	Expand Create an invoice item — response body — period
pricing	JSON	Optional
pricing (anyOf 1)	JSON	Alternative	The pricing information of the invoice item.
pricing (anyOf 1) (anyOf 1)	Model	Alternative	Expand Update an invoice's line item — response body — pricing / The pricing information of the line item / type: price details
pricing (anyOf 2)	null	Alternative
proration	boolean	Required within parent	Whether the invoice item was created automatically as a proration adjustment when the customer switched plans.
proration_details	Model	Optional	Expand Create an invoice item — response body — proration details
quantity	JSON	Required within parent
quantity (anyOf 1)	integer	Alternative	Quantity of units for the invoice item in integer format, with any decimal precision truncated. For the item's full-precision decimal quantity, use `quantity_decimal`. This field will be deprecated in favor of `quantity_decimal` in a future version. If the invoice item is a proration, the quantity of the subscription that the proration was computed for.
quantity (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
quantity_decimal	string	Required within parent	Non-negative decimal with at most 12 decimal places. The quantity of units for the invoice item. Format: decimal
tax_rates	JSON	Optional
tax_rates (anyOf 1)	array	Alternative	The tax rates which apply to the invoice item. When set, the `default_tax_rates` on the invoice do not apply to this invoice item.
tax_rates (anyOf 1)[]	Model	Each item	Expand Create a tax rate — response body
tax_rates (anyOf 2)	null	Alternative
test_clock	JSON	Optional
test_clock (anyOf 1)	JSON	Alternative	ID of the test clock this invoice item belongs to.
test_clock (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
test_clock (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create a test clock — response body
test_clock (anyOf 2)	null	Alternative

Referenced models: Create an invoice item — response body — parent / The parent that generated this invoice item / type: subscription details, Update an invoice's line item — response body — pricing / The pricing information of the line item / type: price details, Create a customer — response body, Delete a customer — response body, Get Customers Customer Discount — response body, Pay an invoice — response body, Create an invoice item — response body — period, Create an invoice item — response body — invoicing rules item, Create an invoice item — response body — proration details, Create a tax rate — response body, Create a test clock — response body

Create an invoice item — request body — body period

Field	Type	Presence	Description and constraints
$	object	Root	The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://docs.stripe.com/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://docs.stripe.com/revenue-recognition/methodology/subscriptions-and-invoicing) for details.
end	integer	Required within parent	Format: unix-time
start	integer	Required within parent	Format: unix-time

Policy, approvals and errors

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