Line Item

A line item represents a subscription or fee attached to a deal. Line items are the basis for revenue recognition in Planhat - mrr, arr, and value roll up from line items to their parent deal and company.

Line items have two product types: **subscription** (recurring revenue with a start and end dates and recurring revenue) and **fee** (one-off charges with a start date and value). Different field rules apply depending on the type.

Subscriptions can either have fixedPeriod be true, in which case fromDate, toDate, length and mrr/arr/value must be defined, or they can have fixedPeriod be false (AKA an evergreen subscription), in which case only fromDate and mrr/arr must be defined. Once an evergreen line item is cancelled, you can set its status as such, and populate an end date.

If you provide the productId when creating a line item, any fields defined on the product level not defined in the creation payload will be autofilled on the new line item, appending the data you provided. E.g. if creating a line item and providing fromDate but no toDate, toDate and length will be populated on the line item from the product catalog.

Line items must belong to a Deal. The recurring or non-recurring revenue (mrr/arr or value) on a line item is recognised as contracted revenue when the parent deal stage is set to Closed Won.

The status of a line item is auto-set to ongoing, but can be set to renewed or lost. This is not important for revenue recognition as that is based on the deal stage and the date-span of line items, not their status, but it can be useful if using Planhat's native auto-renewal features.

mrr and arr are bidirectionally calculated fields, meaning that if one value is provided, the other will be calculated by the system. This also extends to the value field, in cases where the line item has both a fromDate and toDate.

https://api.planhat.com/lineitems

To create a line item, `dealId` and `fromDate` are required. You can reference the deal using its externalId or sourceId: `"dealId": "extid-[deal externalId]"` or `"dealId": "srcid-[deal sourceId]"`.

For **subscriptions**: at least one of `mrr`, `arr`, or `value` is required. For **fees**: `value` is required.

https://api.planhat.com/lineitems/:_id

You can also use prefixed identifiers:

https://api.planhat.com/lineitems/extid-{{externalId}}

Or

https://api.planhat.com/lineitems/srcid-{{sourceId}}

https://api.planhat.com/lineitems/:_id

To get a specific line item, pass the _id in the request URL. Alternatively use a prefixed externalId or sourceId:

https://api.planhat.com/lineitems/extid-{{externalId}}

Or

https://api.planhat.com/lineitems/srcid-{{sourceId}}

https://api.planhat.com/lineitems

The following query params are available:

• companyId — Filter by company id. Multiple ids can be separated by commas.

• dealId — Filter by deal id.

• limit — Limit the list length. Default 100, max 2000.

• offset — Start the list at a specific integer index.

• sort — Sort by a specific property. Prefix with - to reverse sort order.

• select — Return specific properties only. Multiple properties separated by commas.

https://api.planhat.com/lineitems/:_id

To delete a line item, pass the _id in the request URL.

https://api.planhat.com/lineitems

To create a line item, dealId and fromDate are required. To update, specify one of the following keyables in the payload (in order of priority): _id, sourceId, externalId. There is an upper limit of 5,000 items per request.