Invoice Items

Invoice Items represent the component lines of an invoice. An invoice item is added to an invoice by creating or updating it with an invoice field, at which point it will be 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.

Endpoints

POST/v1/invoiceitems

POST/v1/invoiceitems/:id

GET/v1/invoiceitems/:id

GET/v1/invoiceitems

DELETE/v1/invoiceitems/:id

The Invoice Item object

Attributes

idstring
Unique identifier for the object.

amountinteger
Amount (in the currency specified) of the invoice item. This should always be equal to unit_amount * quantity.

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

customerstringExpandable
The ID of the customer who will be billed when this invoice item is billed.

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

metadatanullable 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.

periodobject
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.

pricenullable object
The price of the invoice item.

prorationboolean
Whether the invoice item was created automatically as a proration adjustment when the customer switched plans.

More attributes

objectstring

datetimestamp

discountableboolean

discountsnullable array of stringsExpandable

invoicenullable stringExpandable

livemodeboolean

quantityinteger

subscriptionnullable stringExpandable

subscription_itemnullable string

tax_ratesnullable array of objects

test_clocknullable stringExpandable

unit_amountnullable integer

unit_amount_decimalnullable decimal string

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": {},
  "period": {
    "end": 1680640231,
    "start": 1680640231
  },
  "plan": null,
  "price": {
    "id": "price_1MtGUsLkdIwHu7ix1be5Ljaj",
    "object": "price",
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1680640229,
    "currency": "usd",
    "custom_unit_amount": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": null,
    "product": "prod_NeZe7xbBdJT8EN",
    "recurring": null,
    "tax_behavior": "unspecified",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "one_time",
    "unit_amount": 1099,
    "unit_amount_decimal": "1099"
  },
  "proration": false,
  "quantity": 1,
  "subscription": null,
  "tax_rates": [],
  "test_clock": null,
  "unit_amount": 1099,
  "unit_amount_decimal": "1099"
}

Create an invoice item

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

customerstringRequired
The ID of the customer who will be billed when this invoice item is billed.

amountinteger
The integer amount in cents of the charge to be applied to the upcoming invoice. Passing in a negative amount will reduce the amount_due on the invoice.

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

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

metadataobject
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.

periodobject
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.

pricestring
The ID of the price object.

More parameters

discountableboolean

discountsarray of objects

invoicestring

price_dataobject

quantityinteger

subscriptionstring

tax_behaviorenum

tax_codestring

tax_ratesarray of strings

unit_amountinteger

unit_amount_decimalstring

Returns

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

POST /v1/invoiceitems

Server-side language

curl https://api.stripe.com/v1/invoiceitems \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d customer=cus_NeZei8imSbMVvi \
  -d price=price_1MtGUsLkdIwHu7ix1be5Ljaj

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": {},
  "period": {
    "end": 1680640231,
    "start": 1680640231
  },
  "plan": null,
  "price": {
    "id": "price_1MtGUsLkdIwHu7ix1be5Ljaj",
    "object": "price",
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1680640229,
    "currency": "usd",
    "custom_unit_amount": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": null,
    "product": "prod_NeZe7xbBdJT8EN",
    "recurring": null,
    "tax_behavior": "unspecified",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "one_time",
    "unit_amount": 1099,
    "unit_amount_decimal": "1099"
  },
  "proration": false,
  "quantity": 1,
  "subscription": null,
  "tax_rates": [],
  "test_clock": null,
  "unit_amount": 1099,
  "unit_amount_decimal": "1099"
}

Update an invoice item

Updates the amount or description of an invoice item on an upcoming invoice. Updating an invoice item is only possible before the invoice it’s attached to is closed.

Parameters

amountinteger
The integer amount in cents 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.

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

metadataobject
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.

periodobject
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.

pricestring
The ID of the price object.

More parameters

discountableboolean

discountsarray of objects

price_dataobject

quantityinteger

tax_behaviorenum

tax_codestring

tax_ratesarray of strings

unit_amountinteger

unit_amount_decimalstring

Returns

The updated invoice item object is returned upon success. Otherwise, this call raises an error.

POST /v1/invoiceitems/:id

Server-side language

curl https://api.stripe.com/v1/invoiceitems/ii_1MtGUtLkdIwHu7ixBYwjAM00 \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "metadata[order_id]"=6735

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": {
    "order_id": "6735"
  },
  "period": {
    "end": 1680640231,
    "start": 1680640231
  },
  "plan": null,
  "price": {
    "id": "price_1MtGUsLkdIwHu7ix1be5Ljaj",
    "object": "price",
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1680640229,
    "currency": "usd",
    "custom_unit_amount": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": null,
    "product": "prod_NeZe7xbBdJT8EN",
    "recurring": null,
    "tax_behavior": "unspecified",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "one_time",
    "unit_amount": 1099,
    "unit_amount_decimal": "1099"
  },
  "proration": false,
  "quantity": 1,
  "subscription": null,
  "tax_rates": [],
  "test_clock": null,
  "unit_amount": 1099,
  "unit_amount_decimal": "1099"
}

Retrieve an invoice item

Retrieves the invoice item with the given ID.

Parameters

No parameters.

Returns

Returns an invoice item if a valid invoice item ID was provided. Raises an error otherwise.

GET /v1/invoiceitems/:id

Server-side language

curl https://api.stripe.com/v1/invoiceitems/ii_1MtGUtLkdIwHu7ixBYwjAM00 \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

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": {},
  "period": {
    "end": 1680640231,
    "start": 1680640231
  },
  "plan": null,
  "price": {
    "id": "price_1MtGUsLkdIwHu7ix1be5Ljaj",
    "object": "price",
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1680640229,
    "currency": "usd",
    "custom_unit_amount": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": null,
    "product": "prod_NeZe7xbBdJT8EN",
    "recurring": null,
    "tax_behavior": "unspecified",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "one_time",
    "unit_amount": 1099,
    "unit_amount_decimal": "1099"
  },
  "proration": false,
  "quantity": 1,
  "subscription": null,
  "tax_rates": [],
  "test_clock": null,
  "unit_amount": 1099,
  "unit_amount_decimal": "1099"
}

Invoice Items

The Invoice Item object

Attributes

idstring

amountinteger

currencyenum

customerstringExpandable

descriptionnullable string

metadatanullable object

periodobject

pricenullable object

prorationboolean

More attributesExpand all

objectstring

datetimestamp

discountableboolean

discountsnullable array of stringsExpandable

invoicenullable stringExpandable

livemodeboolean

quantityinteger

subscriptionnullable stringExpandable

subscription_itemnullable string

tax_ratesnullable array of objects

test_clocknullable stringExpandable

unit_amountnullable integer

unit_amount_decimalnullable decimal string

Create an invoice item

Parameters

customerstringRequired

amountinteger

currencyenum

descriptionstring

metadataobject

periodobject

pricestring

More parametersExpand all

discountableboolean

discountsarray of objects

invoicestring

price_dataobject

quantityinteger

subscriptionstring

tax_behaviorenum

tax_codestring

tax_ratesarray of strings

unit_amountinteger

unit_amount_decimalstring

Returns

Update an invoice item

Parameters

amountinteger

descriptionstring

metadataobject

periodobject

pricestring

More parametersExpand all

discountableboolean

discountsarray of objects

price_dataobject

quantityinteger

tax_behaviorenum

tax_codestring

tax_ratesarray of strings

unit_amountinteger

unit_amount_decimalstring

Returns

Retrieve an invoice item

Parameters

Returns

More attributes

More parameters

More parameters