Update a Line Item

PATCH https://api.chartmogul.com/v1/line_items/{LINE_ITEM_UUID}

Updates an invoice line item identified by its UUID.

curl -X PATCH "https://api.chartmogul.com/v1/line_items/li_b86028e7-c28c-4a0f-9518-fbbdbc259824" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
              "amount_in_cents": 12500
          }'
{
  "uuid": "li_b86028e7-c28c-4a0f-9518-fbbdbc259824",
  "external_id": "li_ext_id_00762",
  "type": "subscription",
  "amount_in_cents": 10000,
  "quantity": 1,
  "discount_code": "",
  "discount_amount_in_cents": 0,
  "tax_amount_in_cents": 0,
  "transaction_fees_in_cents": 0,
  "account_code": "",
  "plan_uuid": "pl_5a86bf58-1934-4ccf-9de1-537efa6dd166",
  "plan_external_id": "gold_plan",
  "transaction_fees_currency": null,
  "discount_description": null,
  "event_order": 3,
  "balance_transfer": false,
  "subscription_uuid": "sub_a918d070-3bad-4ddb-8bff-eb8804481d9c",
  "subscription_external_id": "sub_ext_id_00081",
  "prorated": false,
  "proration_type": "full",
  "service_period_start": "2025-06-14T21:39:06.000Z",
  "service_period_end": "2025-07-14T21:39:06.000Z",
  "subscription_set_external_id": "set_ext_id_00012",
  "disabled": false,
  "disabled_at": null,
  "disabled_by": null,
  "user_created": false
}

Path parameters

line_item_uuid string required
The ChartMogul UUID of the line item to be updated.

Query parameters

handle_as_user_edit boolean optional default: false
Valid only for automatic sources (Stripe, Chargebee, Recurly, Braintree, Google Play, App Store Connect and SaaSync integrations); ignored for others.
true — The line item is updated as a user edit and persists through resyncs and reimports. It’s only possible to update a line item with an external ID.
false — The line item update is treated as system-generated and may be overwritten or removed during resyncs and reimports.

Body parameters

These parameters apply to both one-time line items and subscription line items.

type string optional

One of subscription, one_time or trial. Learn more about parameters specific to subscription line items, one-time line items and trial line items.

amount_in_cents integer optional

The final amount charged toward this line item, for the specified quantity and service period, after discounts, taxes and fees have been applied. Expected in cents (or pence for GBP, etc.)

This is the amount that is primarily used to calculate MRR.

quantity integer optional default: 1

The quantity/seats of the subscription being billed by this line item. Can be any non-zero integer. Defaults to 1.

Quantity value does not impact calculation of MRR. It is used for additional segmentation by subscription quantity and generating Subscription Quantity charts.

discount_code string optional

If a discount has been applied to this line item, then an optional reference code to identify the discount.

discount_amount_in_cents integer optional default: 0

If any discount has been applied to this line item, then the discount amount in cents. Defaults to 0.

Discount amount does not impact calculation of MRR.

tax_amount_in_cents integer optional default: 0

The tax that has been applied to this line item, in cents. Defaults to 0.

If specified, we exclude tax amount from MRR.

transaction_fees_in_cents integer optional

The final total transaction fees paid to billing provider and/or payment processor for this line item. Expected in cents (or pence for GBP, etc.).

account_code string optional

The unique account code of this line item used for the purposes of accounting and revenue recognition. Also called “account number” in some systems. Accepts a maximum of 30 alphanumeric characters.

transaction_fees_currency string optional

The three-letter currency code for transaction_fees_in_cents, e.g. USD, EUR, GBP. Refer to the full list of supported currencies.

discount_description string optional

A short description of discount_amount_in_cents.

event_order integer optional

A numeric value that determines the sequence in which events are processed when multiple events occur at the same timestamp.

balance_transfer boolean optional

A boolean stating whether or not this represents a value returned to customer balance.

Subscription line items

The parameters below apply to line item objects that have the type set to subscription.

subscription_external_id string optional

A reference identifier for the subscription in your system. Accepts alphanumeric characters.

subscription_set_external_id string optional

A reference identifier for a set of subscriptions in order to group several subscriptions into one set.

plan_uuid string optional

The ChartMogul UUID of the plan for which this subscription is being charged.

service_period_start timestamp optional

The start of the service period for which this subscription is being charged.

Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

service_period_end timestamp optional

The end of the service period for which this subscription is being charged.

Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

cancelled_at timestamp optional

If this subscription has been cancelled, the time of cancellation.

Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless otherwise specified.

prorated boolean optional

If this is a prorated charge, then set this attribute to true.

proration_type string optional

If not provided, or set to differential, prorated line items are classified as an upgrade or downgrade and added to previously calculated MRR and subscription quantity.

If set to full, prorated line items have a partial service period and do not take previously calculated MRR and subscription quantity into consideration.

If set to differential_mrr, the amount from this prorated line item behaves like differential proration, which means it is added to previously calculated MRR. The quantity from this prorated line item behaves like full proration, which means it is not added to the previously calculated subscription quantity.

One-time line items

The parameters below apply to line item objects that have the type set to one_time.

description string optional
A short description of the non-recurring item being charged to the customer.

Trial line items

Trial line items. On October 2, 2025, we introduced trial as an invoice line item type (alongside the existing subscription and one_time types). We’re gradually making the functionality available to all accounts. Learn more.

The new line item type allows you to create free and paid trials associated with a plan, irrespective of the customer’s free_trial_started_at date.

The parameters below apply to line item objects that have the type set to trial.

subscription_external_id string optional

A reference identifier for the trial subscription in your system. Accepts alphanumeric characters.

subscription_set_external_id string optional

A reference identifier for a set of subscriptions in order to group several subscriptions into one set.

plan_uuid string optional

The ChartMogul UUID of the plan associated with the trial.

service_period_start timestamp optional

The start of the service period of the trial subscription.

Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

service_period_end timestamp optional

The end of the service period of the trial subscription.

Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

cancelled_at timestamp optional

If this trial has been cancelled, the time of cancellation.

Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless otherwise specified.

prorated boolean optional

If this is a prorated charge, then set this attribute to true.

proration_type string optional

If not provided, or set to differential, prorated line items are classified as an upgrade or downgrade and added to previously calculated MRR and subscription quantity.

If set to full, prorated line items have a partial service period and do not take previously calculated MRR and subscription quantity into consideration.

If set to differential_mrr, the amount from this prorated line item behaves like differential proration, which means it is added to previously calculated MRR. The quantity from this prorated line item behaves like full proration, which means it is not added to the previously calculated subscription quantity.

Response

The response contains the updated line item object:

uuid

The UUID of the line_item object generated by ChartMogul.

external_id

The unique external identifier for this line item, as specified by you.

type

The type of line item, one of subscription, one_time or trial, as specified by you.

On October 2, 2025, we introduced trial as an invoice line item type. We’re gradually making the functionality available to all accounts. Learn more.

amount_in_cents

The amount in cents charged toward this line item for the specified service period, after discounts and taxes have been applied, as specified by you.

quantity

The quantity of this line item being billed.

discount_code

A reference code for any discount applied to this line item, as specified by you.

discount_amount_in_cents

The discount amount in cents for this line item, as specified by you.

tax_amount_in_cents

The tax amount in cents for this line item, as specified by you.

transaction_fees_in_cents

The transaction fees in cents for this line item, as specified by you.

account_code

The accounting code for the line item, as specified by you.

plan_uuid

The UUID of the plan object associated with the above subscription object, generated by ChartMogul.

plan_external_id

The unique identifier for the plan associated with this invoice. Typically an identifier from your internal system.

transaction_fees_currency

The transaction fees currency for this line item, as specified by you.

discount_description

The discount amount in cents description for this line item, as specified by you.

event_order

A numeric value that determines the sequence in which events are processed when multiple events occur at the same timestamp, as specified by you.

balance_transfer

A boolean stating whether or not this represents a value returned to customer balance.

subscription_uuid

The UUID of the subscription object generated by ChartMogul.

subscription_set_external_id

An optional unique external identifier for the subscription set to which this subscription belongs, as specified by you.

subscription_external_id

The unique external identifier for this subscription, as specified by you.

prorated

A boolean stating whether or not this is a prorated charge for the subscription object, as specified by you.

proration_type

A string defining the type of proration, with possible values differential, full or differential_mrr.

service_period_start

The start of the service period for which the subscription is being charged, as specified by you.

service_period_end

The end of the service period for which the subscription is being charged, as specified by you.

description

A short description of the one_time line item being charged to the customer, as specified by you.

disabled

A boolean stating whether or not the line item was disabled.

disabled_at

The date and time when the line item was disabled (null for non-disabled records).

disabled_by

The email address of the user who disabled the line item (null for non-disabled records).

user_created

A boolean stating whether or not the line item was created by the user for one of the automatic sources (Stripe, Chargebee, Recurly, Braintree, Google Play, App Store Connect and SaaSync integrations).