post/v1/invoices/{invoice}/lines/{line_item_id}

Update an invoice's line item

Updates an invoice’s line item. Some fields, such as tax_amounts, only live on the invoice line item, so they can only be updated through this endpoint. Other fields, such as amount, live on both the invoice item and the invoice line item, so updates on this endpoint will propagate to the invoice item as well. Updating an invoice’s line item is only possible before the invoice is finalized.

Path parameters

Name	Description
invoice*	Invoice ID of line item
line_item_id*	Invoice line item ID

Request body

Field Type Description

amount

integer

The integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount.

description

string

An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.

discountable

boolean

Controls whether discounts apply to this line item. Defaults to false for prorations or negative line items, and true for all other line items. Cannot be set to true for prorations.

discounts

array<object> | string

The coupons, promotion codes & existing discounts which apply to the line item. Item discounts are applied before invoice discounts. Pass an empty string to remove previously-defined discounts.

expand

array<string>

Specifies which fields in the response should be expanded.

metadata

object | string

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. For type=subscription line items, the incoming metadata specified on the request is directly used to set this value, in contrast to type=invoiceitem line items, where any existing metadata on the invoice line is merged with the incoming data.

period

object

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 enabled, the period will be used to recognize and defer revenue. See the Revenue Recognition documentation for details.

2 nested fields

Field	Type	Description
end*	integer (unix-time)
start*	integer (unix-time)

price_data

object

Data used to generate a new Price object inline.

6 nested fields

Field

Type

Description

currency*

string (currency)

product

string

product_data

object

6 nested fields

Field	Type	Description
description	string
images	array<string>
metadata	object
name*	string
tax_code	string
unit_label	string

tax_behavior

string

unit_amount

integer

unit_amount_decimal

string (decimal)

pricing

object

The pricing information for the invoice item.

1 nested field

Field	Type	Description
price	string

quantity

integer

Non-negative integer. The quantity of units for the line item. Use quantity_decimal instead to provide decimal precision. This field will be deprecated in favor of quantity_decimal in a future version.

quantity_decimal

string (decimal)

Non-negative decimal with at most 12 decimal places. The quantity of units for the line item.

tax_amounts

array<object> | string

A list of up to 20 tax amounts for this line item. This can be useful if you calculate taxes on your own or use a third-party to calculate them. You cannot set tax amounts if any line item has tax_rates or if the invoice has default_tax_rates or uses automatic tax. Pass an empty string to remove previously defined tax amounts.

tax_rates

array<string> | string

The tax rates which apply to the line item. When set, the default_tax_rates on the invoice do not apply to this line item. Pass an empty string to remove previously-defined tax rates.

Response

Field Type Description

amount*

integer

The amount, in cents (or local equivalent).

currency*

string (currency)

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

description

string

An arbitrary string attached to the object. Often useful for displaying to users.

discount_amounts

array<discounts_resource_discount_amount>

The amount of discount calculated per discount for this line item.

array item fields

Field	Type	Description
amount*	integer	The amount, in cents (or local equivalent), of the discount.
discount*	string \| discount \| deleted_discount	The discount that was applied to get this discount amount.

discountable*

boolean

If true, discounts will apply to this line item. Always false for prorations.

discounts*

array<string | discount>

The discounts applied to the invoice line item. Line item discounts are applied before invoice discounts. Use expand[]=discounts to expand each discount.

id*

string

Unique identifier for the object.

invoice

string

The ID of the invoice that contains this line item.

livemode*

boolean

If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

metadata*

object

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. Note that for line items with type=subscription, metadata reflects the current metadata from the subscription associated with the line item, unless the invoice line was directly updated with different metadata after creation.

object*

string

String representing the object's type. Objects of the same type share the same value.

parent

billing_bill_resource_invoicing_lines_parents_invoice_line_item_parent

The parent that generated this line item.

period*

invoice_line_item_period

2 nested fields

Field	Type	Description
end*	integer (unix-time)	The end of the period, which must be greater than or equal to the start. This value is inclusive.
start*	integer (unix-time)	The start of the period. This value is inclusive.

pretax_credit_amounts

array<invoices_resource_pretax_credit_amount>

Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this line item.

array item fields

Field	Type	Description
amount*	integer	The amount, in cents (or local equivalent), of the pretax credit amount.
credit_balance_transaction	string \| billing.credit_balance_transaction	The credit balance transaction that was applied to get this pretax credit amount.
discount	string \| discount \| deleted_discount	The discount that was applied to get this pretax credit amount.
type*	string	Type of the pretax credit amount referenced.

pricing

billing_bill_resource_invoicing_pricing_pricing

The pricing information of the line item.

quantity

integer

Quantity of units for the invoice line item in integer format, with any decimal precision truncated. For the line 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 line item is a proration or subscription, the quantity of the subscription that the proration was computed for.

quantity_decimal

string (decimal)

Non-negative decimal with at most 12 decimal places. The quantity of units for the line item.

subscription string | subscription

subtotal*

integer

The subtotal of the line item, in cents (or local equivalent), before any discounts or taxes.

taxes

array<billing_bill_resource_invoicing_taxes_tax>

The tax information of the line item.

array item fields

Field	Type	Description
amount*	integer	The amount of the tax, in cents (or local equivalent).
tax_behavior*	string	Whether this tax is inclusive or exclusive.
tax_rate_details	billing_bill_resource_invoicing_taxes_tax_rate_details	Additional details about the tax rate. Only present when `type` is `tax_rate_details`.
taxability_reason*	string	The reasoning behind this tax, for example, if the product is tax exempt. The possible values for this field may be extended as new tax rules are supported.
taxable_amount	integer	The amount on which tax is calculated, in cents (or local equivalent).
type*	string	The type of tax information.