The Invoice Line Item object

Attributes

idstring
Unique identifier for the object.

amountinteger
The amount, in cents.

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

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

invoicenullable string
The ID of the invoice that contains this line item.

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

periodobject
The period this line_item covers. For subscription line items, this is the subscription period. For prorations, this starts when the proration was calculated, and ends at the period end of the subscription. For invoice items, this is the time at which the invoice item was created or the period of the item. 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 line item.

prorationboolean
Whether this is a proration.

quantitynullable integer
The quantity of the subscription, if the line item is a subscription or a proration.

typeenum
A string identifying the type of the source of this line item, either an invoiceitem or a subscription.
Possible enum values
invoiceitem
subscription

More attributes

objectstring

amount_excluding_taxnullable integer

discount_amountsnullable array of objects

discountableboolean

discountsarray of stringsExpandable

invoice_itemnullable stringExpandable

livemodeboolean

proration_detailsnullable object

subscriptionnullable stringExpandable

subscription_itemnullable stringExpandable

tax_amountsarray of objects

tax_ratesarray of objects

unit_amount_excluding_taxnullable decimal string

The Invoice Line Item object

{
  "id": "il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R",
  "object": "line_item",
  "amount": 1000,
  "amount_excluding_tax": 1000,
  "currency": "usd",
  "description": "My First Invoice Item (created for API docs)",
  "discount_amounts": [],
  "discountable": true,
  "discounts": [],
  "invoice_item": "ii_1Nzo1ZGgdF1VjufLzD1UUn9R",
  "livemode": false,
  "metadata": {},
  "period": {
    "end": 1696975413,
    "start": 1696975413
  },
  "price": {
    "id": "price_1NzlYfGgdF1VjufL0cVjLJVI",
    "object": "price",
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1696965933,
    "currency": "usd",
    "custom_unit_amount": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": null,
    "product": "prod_OnMHDH6VBmYlTr",
    "recurring": null,
    "tax_behavior": "unspecified",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "one_time",
    "unit_amount": 1000,
    "unit_amount_decimal": "1000"
  },
  "proration": false,
  "proration_details": {
    "credited_items": null
  },
  "quantity": 1,
  "subscription": null,
  "tax_amounts": [],
  "tax_rates": [],
  "type": "invoiceitem",
  "unit_amount_excluding_tax": "1000"
}

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.

Parameters

invoicestringRequired
Invoice ID of line item

line_item_idstringRequired
Invoice line item ID

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

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. One of price or price_data is required.

quantityinteger
Non-negative integer. The quantity of units for the line item.

More parameters

discountableboolean

discountsarray of objects

price_dataobject

tax_amountsarray of objects

tax_ratesarray of strings

Returns

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

POST /v1/invoices/:id/lines/:id

cURL

curl -X POST https://api.stripe.com/v1/invoices/in_1NuhUa2eZvKYlo2CWYVhyvD9/lines/il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

Response

{
  "id": "il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R",
  "object": "line_item",
  "amount": 1000,
  "amount_excluding_tax": 1000,
  "currency": "usd",
  "description": "My First Invoice Item (created for API docs)",
  "discount_amounts": [],
  "discountable": true,
  "discounts": [],
  "invoice_item": "ii_1Nzo1ZGgdF1VjufLzD1UUn9R",
  "livemode": false,
  "metadata": {},
  "period": {
    "end": 1696975413,
    "start": 1696975413
  },
  "price": {
    "id": "price_1NzlYfGgdF1VjufL0cVjLJVI",
    "object": "price",
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1696965933,
    "currency": "usd",
    "custom_unit_amount": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": null,
    "product": "prod_OnMHDH6VBmYlTr",
    "recurring": null,
    "tax_behavior": "unspecified",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "one_time",
    "unit_amount": 1000,
    "unit_amount_decimal": "1000"
  },
  "proration": false,
  "proration_details": {
    "credited_items": null
  },
  "quantity": 1,
  "subscription": null,
  "tax_amounts": [],
  "tax_rates": [],
  "type": "invoiceitem",
  "unit_amount_excluding_tax": "1000"
}

Retrieve an invoice's line items

When retrieving an invoice, you’ll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Parameters

No parameters.

More parameters

ending_beforestring

limitinteger

starting_afterstring

Returns

Returns a list of line_item objects.

GET /v1/invoices/:id/lines

Server-side language

curl https://api.stripe.com/v1/invoices/in_1NpHok2eZvKYlo2CyeiBref0/lines \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

Response

{
  "object": "list",
  "url": "/v1/invoices/in_1NpHiG2eZvKYlo2CZV0ZkEBT/lines",
  "has_more": false,
  "data": [
    {
      "id": "il_tmp_1NpHiK2eZvKYlo2C9NdV8VrI",
      "object": "line_item",
      "amount": 129999,
      "amount_excluding_tax": 129999,
      "currency": "usd",
      "description": "My First Invoice Item (created for API docs)",
      "discount_amounts": [],
      "discountable": true,
      "discounts": [],
      "invoice_item": "ii_1NpHiK2eZvKYlo2C9NdV8VrI",
      "livemode": false,
      "metadata": {},
      "period": {
        "end": 1694467932,
        "start": 1694467932
      },
      "price": {
        "id": "price_1NpEIa2eZvKYlo2CXcy5DRPA",
        "object": "price",
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1694454804,
        "currency": "usd",
        "custom_unit_amount": null,
        "livemode": false,
        "lookup_key": null,
        "metadata": {},
        "nickname": null,
        "product": "prod_OcTFTbV7qh48bd",
        "recurring": null,
        "tax_behavior": "unspecified",
        "tiers_mode": null,
        "transform_quantity": null,
        "type": "one_time",
        "unit_amount": 129999,
        "unit_amount_decimal": "129999"
      },
      "proration": false,
      "proration_details": {
        "credited_items": null
      },
      "quantity": 1,
      "subscription": null,
      "tax_amounts": [],
      "tax_rates": [],
      "type": "invoiceitem",
      "unit_amount_excluding_tax": "129999"
    }
  ]
}

Retrieve an upcoming invoice's line items

When retrieving an upcoming invoice, you’ll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Parameters

customerstring
The identifier of the customer whose upcoming invoice you’d like to retrieve. If automatic_tax is enabled then one of customer, customer_details, subscription, or schedule must be set.

subscriptionstring
The identifier of the subscription for which you’d like to retrieve the upcoming invoice. If not provided, but a subscription_details.items is provided, you will preview creating a subscription with those items. If neither subscription nor subscription_details.items is provided, you will retrieve the next upcoming invoice from among the customer’s subscriptions.

More parameters

automatic_taxobject

couponstringDeprecated

currencyenum

customer_detailsobject

discountsarray of objects

ending_beforestring

invoice_itemsarray of objects

issuerobjectConnect only

limitinteger

on_behalf_ofstringConnect only

preview_modeenum

schedulestring

schedule_detailsobject

starting_afterstring

subscription_billing_cycle_anchorstring | timestampDeprecated

subscription_cancel_attimestampDeprecated

subscription_cancel_at_period_endbooleanDeprecated

subscription_cancel_nowbooleanDeprecated

subscription_default_tax_ratesarray of stringsDeprecated

subscription_detailsobject

subscription_itemsarray of objectsDeprecated

subscription_proration_behaviorenumDeprecated

subscription_proration_datetimestampDeprecated

subscription_resume_atstringDeprecated

subscription_start_datetimestampDeprecated

subscription_trial_endstring | timestampDeprecated

Returns

Returns a list of line_item objects.

GET /v1/invoices/upcoming/lines

Server-side language

curl -G https://api.stripe.com/v1/invoices/upcoming/lines \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d customer=cus_OgeRVYRv3sHroi

Response

{
  "object": "list",
  "url": "/v1/invoices/upcoming/lines",
  "has_more": false,
  "data": [
    {
      "id": "il_tmp_1NtH5qBHO5VeT9SUzhbifVXt",
      "object": "line_item",
      "amount": 1000,
      "amount_excluding_tax": 1000,
      "currency": "usd",
      "description": "My First Invoice Item (created for API docs)",
      "discount_amounts": [],
      "discountable": true,
      "discounts": [],
      "invoice_item": "ii_1NtH5qBHO5VeT9SUzhbifVXt",
      "livemode": false,
      "metadata": {},
      "period": {
        "end": 1695418858,
        "start": 1695418858
      },
      "price": {
        "id": "price_1NrpbEBHO5VeT9SUHp6xMwKA",
        "object": "price",
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1695074844,
        "currency": "usd",
        "custom_unit_amount": null,
        "livemode": false,
        "lookup_key": null,
        "metadata": {},
        "nickname": null,
        "product": "prod_Of9vdHHGRaGOio",
        "recurring": null,
        "tax_behavior": "unspecified",
        "tiers_mode": null,
        "transform_quantity": null,
        "type": "one_time",
        "unit_amount": 1000,
        "unit_amount_decimal": "1000"
      },
      "proration": false,
      "proration_details": {
        "credited_items": null
      },
      "quantity": 1,
      "subscription": null,
      "tax_amounts": [],
      "tax_rates": [],
      "type": "invoiceitem",
      "unit_amount_excluding_tax": "1000"
    }
    {...}
    {...}
  ],
}

Bulk add invoice line items

Adds multiple line items to an invoice. This is only possible when an invoice is still a draft.

Parameters

linesarray of objectsRequired
The line items to add.

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

Returns

The updated invoice with newly added line items is returned upon success. Otherwise, this call raises an error.

POST /v1/invoices/:id/add_lines

Server-side language

curl https://api.stripe.com/v1/invoices/in_1NuhUa2eZvKYlo2CWYVhyvD9/add_lines \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "lines[0][description]"="test description" \
  -d "lines[0][amount]"=799 \
  -d "lines[1][invoice_item]"=ii_1NuLVd2eZvKYlo2CRWY0Hqgi

Response

{
  "id": "in_1NuhUa2eZvKYlo2CWYVhyvD9",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Stripe.com",
  "account_tax_ids": null,
  "amount_due": 998,
  "amount_paid": 0,
  "amount_remaining": 998,
  "amount_shipping": 0,
  "application": null,
  "application_fee_amount": null,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "automatic_tax": {
    "enabled": false,
    "liability": null,
    "status": null
  },
  "billing_reason": "manual",
  "charge": null,
  "collection_method": "charge_automatically",
  "created": 1695758664,
  "currency": "usd",
  "custom_fields": null,
  "customer": "cus_9s6XKzkNRiz8i3",
  "customer_address": null,
  "customer_email": "test@test.com",
  "customer_name": null,
  "customer_phone": null,
  "customer_shipping": null,
  "customer_tax_exempt": "none",
  "customer_tax_ids": [],
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discount": null,
  "discounts": [],
  "due_date": null,
  "effective_at": null,
  "ending_balance": null,
  "footer": null,
  "from_invoice": null,
  "hosted_invoice_url": null,
  "invoice_pdf": null,
  "issuer": {
    "type": "self"
  },
  "last_finalization_error": null,
  "latest_revision": null,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "il_1NuhUa2eZvKYlo2CC98Fg3Bo",
        "object": "line_item",
        "amount": 799,
        "amount_excluding_tax": 799,
        "currency": "usd",
        "description": "test description",
        "discount_amounts": [],
        "discountable": true,
        "discounts": [],
        "invoice_item": "ii_1NuhUa2eZvKYlo2CGeF7Qgx0",
        "livemode": false,
        "metadata": {},
        "period": {
          "end": 1695758664,
          "start": 1695758664
        },
        "price": {
          "id": "price_1NuhLA2eZvKYlo2Cq1tIGEBp",
          "object": "price",
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1695758080,
          "currency": "usd",
          "custom_unit_amount": null,
          "livemode": false,
          "lookup_key": null,
          "metadata": {},
          "nickname": null,
          "product": "prod_Oi7aO1GPi1dWX7",
          "recurring": null,
          "tax_behavior": "unspecified",
          "tiers_mode": null,
          "transform_quantity": null,
          "type": "one_time",
          "unit_amount": 799,
          "unit_amount_decimal": "799"
        },
        "proration": false,
        "proration_details": {
          "credited_items": null
        },
        "quantity": 1,
        "subscription": null,
        "tax_amounts": [],
        "tax_rates": [],
        "type": "invoiceitem",
        "unit_amount_excluding_tax": "799"
      },
      {
        "id": "il_1NuLVe2eZvKYlo2Canh35EfU",
        "object": "line_item",
        "amount": 199,
        "amount_excluding_tax": 199,
        "currency": "usd",
        "description": "Canned Coffee",
        "discount_amounts": [],
        "discountable": true,
        "discounts": [],
        "invoice_item": "ii_1NuLVd2eZvKYlo2CRWY0Hqgi",
        "livemode": false,
        "metadata": {},
        "period": {
          "end": 1695674161,
          "start": 1695674161
        },
        "price": {
          "id": "price_1NuI212eZvKYlo2CWgdD8kET",
          "object": "price",
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1695660793,
          "currency": "usd",
          "custom_unit_amount": null,
          "livemode": false,
          "lookup_key": null,
          "metadata": {},
          "nickname": null,
          "product": "prod_OhhQNWDYdIbXYv",
          "recurring": null,
          "tax_behavior": "unspecified",
          "tiers_mode": null,
          "transform_quantity": null,
          "type": "one_time",
          "unit_amount": 199,
          "unit_amount_decimal": "199"
        },
        "proration": false,
        "proration_details": {
          "credited_items": null
        },
        "quantity": 1,
        "subscription": null,
        "tax_amounts": [],
        "tax_rates": [],
        "type": "invoiceitem",
        "unit_amount_excluding_tax": "199"
      }
    ],
    "has_more": false,
    "url": "/v1/invoices/upcoming/lines?customer=cus_9s6XKzkNRiz8i3"
  },
  "livemode": false,
  "metadata": {},
  "next_payment_attempt": null,
  "number": null,
  "on_behalf_of": null,
  "paid": false,
  "paid_out_of_band": false,
  "payment_intent": null,
  "payment_settings": {
    "default_mandate": null,
    "payment_method_options": null,
    "payment_method_types": null
  },
  "period_end": 1688482163,
  "period_start": 1688395763,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "quote": null,
  "receipt_number": null,
  "redaction": null,
  "rendering": null,
  "rendering_options": null,
  "shipping_cost": null,
  "shipping_details": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "status": "draft",
  "status_transitions": {
    "finalized_at": null,
    "marked_uncollectible_at": null,
    "paid_at": null,
    "voided_at": null
  },
  "subscription": null,
  "subscription_details": {
    "metadata": null
  },
  "subtotal": 998,
  "subtotal_excluding_tax": 998,
  "tax": null,
  "test_clock": null,
  "total": 998,
  "total_discount_amounts": [],
  "total_excluding_tax": 998,
  "total_tax_amounts": [],
  "transfer_data": null,
  "webhooks_delivered_at": null
}

The Invoice Line Item object

Attributes

idstring

amountinteger

currencyenum

descriptionnullable string

invoicenullable string

metadataobject

periodobject

pricenullable object

prorationboolean

quantitynullable integer

typeenum

More attributesExpand all

objectstring

amount_excluding_taxnullable integer

discount_amountsnullable array of objects

discountableboolean

discountsarray of stringsExpandable

invoice_itemnullable stringExpandable

livemodeboolean

proration_detailsnullable object

subscriptionnullable stringExpandable

subscription_itemnullable stringExpandable

tax_amountsarray of objects

tax_ratesarray of objects

unit_amount_excluding_taxnullable decimal string

Update an invoice's line item

Parameters

invoicestringRequired

line_item_idstringRequired

amountinteger

descriptionstring

metadataobject

periodobject

pricestring

quantityinteger

More parametersExpand all

discountableboolean

discountsarray of objects

price_dataobject

tax_amountsarray of objects

tax_ratesarray of strings

Returns

Retrieve an invoice's line items

Parameters

More parametersExpand all

ending_beforestring

limitinteger

starting_afterstring

Returns

Retrieve an upcoming invoice's line items

Parameters

customerstring

subscriptionstring

More parametersExpand all

automatic_taxobject

couponstringDeprecated

currencyenum

customer_detailsobject

discountsarray of objects

ending_beforestring

invoice_itemsarray of objects

issuerobjectConnect only

limitinteger

on_behalf_ofstringConnect only

preview_modeenum

schedulestring

schedule_detailsobject

starting_afterstring

subscription_billing_cycle_anchorstring | timestampDeprecated

subscription_cancel_attimestampDeprecated

subscription_cancel_at_period_endbooleanDeprecated

subscription_cancel_nowbooleanDeprecated

subscription_default_tax_ratesarray of stringsDeprecated

subscription_detailsobject

subscription_itemsarray of objectsDeprecated

subscription_proration_behaviorenumDeprecated

subscription_proration_datetimestampDeprecated

subscription_resume_atstringDeprecated

More attributes

More parameters

More parameters

More parameters