Billing Primitives

Every dollar on chrt flows through four objects: a rate sheet prices the work, a line item group records the resulting charges for one task group, a statement rolls one or more line item groups into an invoice, and a ledger (optional) groups statements into a recurring billing period. This page is the data model behind every billing UI.

Payment vectors

Before any of the primitives, you need to know who is paying whom. chrt has three directional payment vectors:

The owner of a payment vector is the payment owner — they’re the one who creates the rate sheet and bills against it. Each rate sheet, line item group, and statement carries the payment vector it belongs to so every party sees only the figures they’re entitled to.

Rate sheet

A rate sheet defines the prices for a standard set of work. It’s a pricing template — base mileage, additional mileage, fuel surcharge, wait time, surcharges for dangerous goods, after-hours, weekend, and holiday — that attaches to a task group to generate billable charges.

Rate sheets are kinded to match the kind of work being priced:

A rate sheet also carries cargo_types and vehicle_types arrays. When you assign a courier to a task group, chrt checks that the rate sheet’s cargo and vehicle scope covers the cargo on that group. See Cargo types for the full enum.

Default rate sheets

Payment owners can set default rate sheets at three levels:

• Org default — fallback used if nothing more specific applies.
• Connection default — auto-applies to every order assigned across a given connection. See Connections.
• Driver default (for PPD) — what a courier pays a specific driver.

Defaults are conveniences; you can always override on an individual task group.

Line item group

A line item group (LIG) is the list of charges generated for one task group from one rate sheet. When a task group is assigned a rate sheet, chrt generates a LIG automatically with one line item per chargeable component — base rate, additional mileage, fuel, wait time, surcharges. Each line item has a quantity, a rate, a computed amount, and a comment.

LIGs also carry:

• Messages and attachments — drivers, couriers, forwarders, and shippers can upload receipts and discuss or dispute charges inline on the LIG.
• Adjustments — payment owners can adjust an individual line item up or down with an adjustment comment, or add ad-hoc line items the rate sheet didn’t cover.
• Status — the LIG’s lifecycle independent of its statement.

Line item group states

Statement

A statement is the boundary between recorded charges and an actual invoice sent for payment. A statement bundles one or more LIGs into a single amount due, attaches a Stripe invoice (or marks the settlement as off-platform), and tracks the payment lifecycle.

Common shapes:

• One statement per order for shippers and forwarders — one LIG per task group on the order.
• One statement per task group for couriers — they get paid as they complete each job.
• Manually grouped statements for drivers — couriers usually pay drivers on a pay-period basis, so the courier groups multiple LIGs into one bi-weekly statement.

Statement states

Settlement type

See auth and payments for how Stripe Connect is set up.

Billing ledger

A billing ledger is an optional layer on top of statements: it groups work between two parties across a recurring period (a week, a month, a pay cycle) into one rolling agreement. Ledgers are keyed by:

• Task group type (ground, flights, or OBC — optional scoping).
• Payment origin org / off-platform shipper org.
• Payment destination org / off-platform provider / driver.

A ledger has a status of active or inactive. Active ledgers roll new task-group LIGs into the current period; deactivating a ledger stops new work from rolling in but does not touch already-settled history.

Use ledgers when you want a single recurring invoice or pay-period statement for one partner rather than a separate statement per task group.

How the pieces connect

Order
└── Task Group
    └── Rate Sheet (assigned)
        └── Line Item Group (auto-generated)
            ├── line_item: base_rate
            ├── line_item: additional_mileage
            ├── line_item: fuel
            └── line_item: dangerous_goods (if applicable)
                │
                ▼
            Statement (one or more LIGs)
                │
                ▼
            (optional) Billing Ledger Period
                │
                ▼
            Stripe invoice  or  off-platform settlement

Related guides

• Cargo types — cargo type scopes rate sheets.
• Connections — default rate sheets per connection.
• Orders, task groups, segments, stops — rate sheets attach to task groups, not orders.
• Roles and permissions — which roles can manage rate sheets and statements.
• Rate sheets (shippers) — create and manage rate sheets as a shipper.
• Billing for forwarders — earn and pay through chrt.
• Billing for couriers — get paid for the task groups you complete.