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

Update an invoice item 

Billing
Invoice Items
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.

    • period.endtimestampRequired

      The end of the period, which must be greater than or equal to the start. This value is inclusive.

    • period.starttimestampRequired

      The start of the period. This value is inclusive.

  • pricingobject

    The pricing information for the invoice item.

    • pricing.pricestring

      The ID of the price object.

More parameters

  • discountableboolean

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

  • discountsarray of objects

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

    • discounts.couponstring

      ID of the coupon to create a new discount for.

    • discounts.discountstring

      ID of an existing discount on the object (or one of its ancestors) to reuse.

    • discounts.promotion_codestring

      ID of the promotion code to create a new discount for.

  • price_dataobject

    Data used to generate a new Price object inline.

    • price_data.currencyenumRequired

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

    • price_data.productstringRequired

      The ID of the Product that this Price will belong to.

    • price_data.tax_behaviorenumRecommended if calculating taxes

      Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

      Possible enum values
      exclusive
      inclusive
      unspecified

    • price_data.unit_amountinteger

      A positive integer in cents (or 0 for a free price) representing how much to charge.

    • price_data.unit_amount_decimalstringRequired conditionally

      Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.

  • quantityinteger

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

  • tax_behaviorenumRecommended if calculating taxes

    Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

    Possible enum values
    exclusive
    inclusive
    unspecified

  • tax_codestringRecommended if calculating taxes

    A tax code ID.

  • tax_ratesarray of strings

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

  • unit_amount_decimalstring

    The decimal unit amount in cents of the charge to be applied to the upcoming invoice. This unit_amount_decimal will be multiplied by the quantity to get the full amount. Passing in a negative unit_amount_decimal will reduce the amount_due on the invoice. Accepts at most 12 decimal places.

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_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -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"
  },
  "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,
  "tax_rates": [],
  "test_clock": null
}