Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

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

More parameters

  • discountableboolean

  • discountsarray of objects

  • invoicestring

  • price_dataobject

  • quantityinteger

  • subscriptionstring

  • tax_behaviorenumRecommended if calculating taxes

  • tax_codestringRecommended if calculating taxes

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

More parameters

  • discountableboolean

  • discountsarray of objects

  • price_dataobject

  • quantityinteger

  • tax_behaviorenumRecommended if calculating taxes

  • tax_codestringRecommended if calculating taxes

  • 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
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
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"
}

List all invoice items 

Returns a list of your invoice items. Invoice items are returned sorted by creation date, with the most recently created invoice items appearing first.

Parameters

  • customerstring

    The identifier of the customer whose invoice items to return. If none is provided, all invoice items will be returned.

More parameters

  • createdobject

  • ending_beforestring

  • invoicestring

  • limitinteger

  • pendingboolean

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit invoice items, starting after invoice item starting_after. Each entry in the array is a separate invoice item object. If no more invoice items are available, the resulting array will be empty.

GET /v1/invoiceitems
curl -G https://api.stripe.com/v1/invoiceitems \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/invoiceitems",
  "has_more": false,
  "data": [
    {
      "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"
    }
  ]
}