Propose line item

POST

/billing/line_item_groups/propose_line_item/v1/:line_item_group_id

POST

/billing/line_item_groups/propose_line_item/v1/:line_item_group_id

1 import { ChrtClient } from "@chrt-inc/typescript-sdk";
2 
3 async function main() {
4     const client = new ChrtClient({
5         token: "YOUR_TOKEN_HERE",
6     });
7     await client.billing.lineItemGroups.proposeLineItemV1("line_item_group_id", {
8         item: "base_rate",
9         rate: 1.1,
10         quantity: 1.1,
11     });
12 }
13 main();

1 {
2   "schema_version": 1,
3   "_id": "_id",
4   "owned_by_org_id": "owned_by_org_id",
5   "task_group_id": "task_group_id",
6   "order_id": "order_id",
7   "order_short_id": "order_short_id",
8   "order_off_chrt_reference_id": "order_off_chrt_reference_id",
9   "rate_sheet_id": "rate_sheet_id",
10   "agreement_line_item_ids": [
11     "agreement_line_item_ids"
12   ],
13   "agreement_amount": 1.1,
14   "amendment_line_item_ids": [
15     "amendment_line_item_ids"
16   ],
17   "amendment_amount": 1.1,
18   "pending_line_item_ids": [
19     "pending_line_item_ids"
20   ],
21   "pending_amount": 1.1,
22   "denied_line_item_ids": [
23     "denied_line_item_ids"
24   ],
25   "denied_amount": 1.1,
26   "line_item_group_s3_object_metadata_ids": [
27     "line_item_group_s3_object_metadata_ids"
28   ],
29   "statement_id": "statement_id",
30   "settlement_type": "stripe_connect",
31   "payment_origin_org_id": "payment_origin_org_id",
32   "payment_origin_off_chrt_shipper_org_id": "payment_origin_off_chrt_shipper_org_id",
33   "payment_destination_org_id": "payment_destination_org_id",
34   "payment_destination_off_chrt_provider_org_id": "payment_destination_off_chrt_provider_org_id",
35   "payment_destination_driver_id": "payment_destination_driver_id",
36   "status": "staged",
37   "finalized_at_timestamp": "2024-01-15T09:30:00Z",
38   "finalized_by_user_id": "finalized_by_user_id",
39   "messages": [
40     {
41       "message": "message",
42       "user_id": "user_id",
43       "org_id": "org_id",
44       "timestamp": "2024-01-15T09:30:00Z"
45     }
46   ]
47 }

Counterparty proposes a draft AD_HOC LineItem on a non-FINALIZED LineItemGroup. The item lands in pending_line_item_ids with ad_hoc__status=PENDING; the owner resolves it via approve/deny. Caller must be on the LIG (origin or destination) but not the owner. | authz_personas=[lig_org_operators] | (LineItemClientCreate1) -> (LineItemGroup1)

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

line_item_group_idstringRequired

Request

This endpoint expects an object.

itemenumRequired

TODO - improve domain model notes here.

unified catalog for all TG types and other services, e.g. IoT tracking devices
some line items will match TG type more frequently
…

ratedoubleRequired

quantitydoubleRequired

schema_versionintegerOptionalDefaults to 1

commentsstringOptional<=524288 characters

unitsenumOptional

adjustmentdoubleOptional

adjustment_commentsstringOptional<=524288 characters

Response

Successful Response

schema_versioninteger

_idstring

owned_by_org_idstring

Must be a string starting with org_

task_group_idstring

order_idstring

order_short_idstring

order_off_chrt_reference_idstringformat: "^[A-Za-z0-9._~\-]{1,64}$"1-64 characters

Must be a URL-safe string of 1-64 characters. Allowed characters: A-Z, a-z, 0-9, ’.’, ’_’, ’~’, ’-’ (RFC 3986 unreserved).

rate_sheet_idstring

agreement_line_item_idslist of strings

agreement_amountdoubleDefaults to 0

amendment_line_item_idslist of strings

amendment_amountdoubleDefaults to 0

pending_line_item_idslist of strings

pending_amountdoubleDefaults to 0

denied_line_item_idslist of strings

denied_amountdoubleDefaults to 0

line_item_group_s3_object_metadata_idslist of strings

statement_idstring

settlement_typeenum

payment_origin_org_idstring

Must be a string starting with org_

payment_origin_off_chrt_shipper_org_idstring

payment_destination_org_idstring

Must be a string starting with org_

payment_destination_off_chrt_provider_org_idstring

payment_destination_driver_idstring

statusenum

LineItemGroup lifecycle.

The pre-FINALIZED window is a single STAGED state — operators compose the bundle (add/remove owner ad-hoc into amendment, propose/approve/deny counterparty items) and then call finalize/v1 to lock it. Every state past STAGED is reached by a deliberate transition (finalize/v1, open_invoice/v1, sync routes).

The legacy PENDING_RATES, PENDING_CALCULATION, and ADJUSTABLE states were tied to the old auto-recalc-on-mutation hooks. Bucket amounts ARE kept in sync on every mutation today (see the “Amounts” section of the module docstring), but that’s a write-time invariant, not a status — modeling “is the amount fresh?” as LIG status duplicates information and was dropped 2026-05-03. The worklist principle (an empty agreement_line_item_ids bucket or an unfilled <vector>_line_item_group_id field IS the operator signal) makes the intermediate states redundant in any case.

finalized_at_timestampdatetime

finalized_by_user_idstring

Must be a string starting with user_

messageslist of objects

Errors

422

Line Item Groups Propose Line Item V1request Unprocessable Entity Error