Create a Line Item
POST https://api.chartmogul.com/v1/invoices/{INVOICE_UUID}/line_items
Creates a line item for a specified invoice.
curl -X POST "https://api.chartmogul.com/v1/invoices/inv_cf35bc9c-fceb-4008-98b0-a7f89edc3191/line_items" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"type": "subscription",
"amount_in_cents": 10000,
"quantity": 1,
"external_id": "li_ext_id_00762",
"event_order": 3,
"subscription_external_id": "sub_added_line_item_via_api_1",
"plan_uuid": "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
"service_period_start": "2022-11-01T00:00:00.000Z",
"service_period_end": "2022-12-01T00:00:00.000Z"
}'
{
"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": true
}
Behavior with different types of sources. For automatic sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration), we now permanently store all records added, edited or disabled using the API. Such edits are preserved after customer re-syncs and automatic updates.
For these sources, use the include_edit_histories
query parameter when retrieving line items to fetch both the original values imported from the billing system and the edited values. The with_disabled
query parameter allows you to include disabled records in the response.
For other automatic sources, edits done via the API may be overwritten during customer re-syncs or automatic updates.
For custom sources, edits are not stored separately from the original data.
External ID requirement. When creating a line item in sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration), you must provide an external ID. For these sources, we now permanently store edits made using the API and need this information to associate the edits with the edited record.
Path parameters
invoice_uuid
string required- The ChartMogul UUID of the invoice to which you’re adding the line item.
Body parameters
These parameters apply to both one-time line items and subscription line items.
type
string required-
Either
subscription
orone_time
. See the subscription line items section and the one-time line items section for more details about parameters specific to the set type. amount_in_cents
integer required-
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.).
external_id
string optional-
A unique identifier specified by you for the line item. Typically an identifier from your internal system. Accepts alphanumeric characters.
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
-
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 required-
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 required optional-
The ChartMogul UUID of the plan for which this subscription is being charged.
service_period_start
timestamp required-
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 required-
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. 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 likedifferential
proration, which means it is added to previously calculated MRR. The quantity from this prorated line item behaves likefull
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.
Response
The response contains the following data:
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, either
subscription
orone_time
, as specified by you. 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
ordifferential_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 sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration).