Invoice Items

Invoice Items represent the component lines of an invoice. When you create an invoice item with an invoice field, it is attached to the specified invoice and included as an invoice line item within invoice.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. 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.

Was this section helpful? Yes No

Create an invoice item

POST / v1 / invoiceitems

Update an invoice item

POST / v1 / invoiceitems /:id

Retrieve an invoice item

GET / v1 / invoiceitems /:id

List all invoice items

GET / v1 / invoiceitems

Delete an invoice item

DELETE / v1 / invoiceitems /:id

The Invoice Item object

Attributes

id string Unique identifier for the object.
amount integer Amount (in the currency specified) of the invoice item. This should always be equal to unit_amount * quantity.
currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer string Expandable The ID of the customer to bill for this invoice item.
customer _ account nullable string The ID of the account to bill for this invoice item.
description nullable string An arbitrary string attached to the object. Often useful for displaying to users.
metadata nullable map 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.
parent nullable object The parent that generated this invoice item.
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.
pricing nullable object The pricing information of the invoice item.
proration boolean Whether the invoice item was created automatically as a proration adjustment when the customer switched plans.

More attributes

object string, value is "invoiceitem"
date timestamp
discountable boolean
discounts nullable array of strings Expandable
frozen _ fields nullable array of enums
invoice nullable string Expandable
invoicing _ rules array of objects Preview feature
livemode boolean
net _ amount nullable integer
proration _ details nullable object
quantity integer Deprecated
quantity _ decimal decimal string
tax _ rates nullable array of objects
test _ clock nullable string Expandable

The Invoice Item object

{ "id": "ii_1MtGUtLkdIwHu7ixBYwjAM00", "object": "invoiceitem", "amount": 1099, "currency": "usd", "customer": "cus_NeZei8imSbMVvi", "date": 1680640231, "description": "T-shirt", "discountable": true, "discounts": [], "invoice": null, "livemode": false, "metadata": {}, "parent": null, "period": { "end": 1680640231, "start": 1680640231 }, "pricing": { "price_details": { "price": "price_1MtGUsLkdIwHu7ix1be5Ljaj", "product": "prod_NeZe7xbBdJT8EN" }, "type": "price_details", "unit_amount_decimal": "1099" }, "proration": false, "quantity": 1, "quantity_decimal": "1", "tax_rates": [], "test_clock": null}

Create an invoice item

POST / v1 / invoiceitems

Creates an item to be added to a draft invoice (up to 250 items per invoice). If no invoice is specified, the item will be on the next invoice created for the customer specified.

Parameters

amount integer The integer amount in the smallest currency unit of the charge to be applied to the upcoming invoice. Passing in a negative amount will reduce the amount_due on the invoice.
currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer string The ID of the customer to bill for this invoice item.
customer _ account string The ID of the account representing the customer to bill for this invoice item.
description string An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.
metadata map 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.
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.
pricing object The pricing information for the invoice item.

More parameters

discountable boolean
discounts array of objects
invoice string
price _ data object
quantity integer Deprecated
quantity _ decimal string
subscription string
tax _ behavior enum Recommended if calculating taxes
tax _ code string Recommended if calculating taxes
tax _ rates array of strings
unit _ amount _ decimal string

Returns

The created invoice item object is returned if successful. Otherwise, this call raises an error.

Response

{ "id": "ii_1MtGUtLkdIwHu7ixBYwjAM00", "object": "invoiceitem", "amount": 1099, "currency": "usd", "customer": "cus_NeZei8imSbMVvi", "date": 1680640231, "description": "T-shirt", "discountable": true, "discounts": [], "invoice": null, "livemode": false, "metadata": {}, "parent": null, "period": { "end": 1680640231, "start": 1680640231 }, "pricing": { "price_details": { "price": "price_1MtGUsLkdIwHu7ix1be5Ljaj", "product": "prod_NeZe7xbBdJT8EN" }, "type": "price_details", "unit_amount_decimal": "1099" }, "proration": false, "quantity": 1, "quantity_decimal": "1", "tax_rates": [], "test_clock": null}