> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.chrt.com/prod/docs/concepts/billing-primitives/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.chrt.com/_mcp/server. # Billing Primitives > How chrt models billing — payment vectors (SPP, PPP, PPD), rate sheets, line item groups, statements, and ledgers. The full lifecycle from work performed to invoice paid. 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**: | Code | Vector | Who owns it | | ------- | ----------------------- | --------------------------------------------------------- | | **SPP** | `shipper_pay_provider` | The provider (forwarder or courier) charging the shipper. | | **PPP** | `provider_pay_provider` | The forwarder paying a downstream courier. | | **PPD** | `provider_pay_driver` | The courier paying their own driver. | 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: | Rate sheet kind | Used for task group type | Pricing shape | | --------------- | ------------------------ | ---------------------------------------------------------- | | **Ground** | `chrt_ground_provider` | Distance-based — base + additional mileage + surcharges. | | **Flights** | `cargo_on_flight` | Air cargo — quantity, rate, airline / service-type fields. | | **OBC** | `onboard_courier` | Day-rate based for hand-carry work. | 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](/docs/concepts/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](/docs/concepts/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 | Status | Meaning | | --------------- | ------------------------------------------------------------- | | `staged` | Generated from the rate sheet. Open to edits and adjustments. | | `finalized` | Marked as ready for collection. Edits are locked. | | `open` | Attached to a statement that has been issued for payment. | | `paid` | The parent statement was paid. | | `uncollectible` | The parent statement was marked uncollectible. | ## 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 | Status | Meaning | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `staged` | The statement exists but hasn't been issued. Edits to its LIGs are still possible. | | `open` | Issued — a Stripe invoice has been generated and is awaiting payment, or the statement is marked open for off-platform settlement. | | `paid` | Payment has been confirmed (Stripe-paid or marked paid for off-platform settlements). | | `uncollectible` | The payment owner has written this statement off as uncollectible. | ### Settlement type | Settlement type | Meaning | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `stripe_connect` | The payee org has a Stripe Connect account; chrt issues the Stripe invoice and marks the statement paid on Stripe confirmation. | | `off_chrt` | Settlement happens outside chrt; the payment owner manually marks the statement open and paid as the money moves. | See [auth and payments](https://chrt.com/help) 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](/docs/concepts/cargo-types) — cargo type scopes rate sheets. * [Connections](/docs/concepts/connections) — default rate sheets per connection. * [Orders, task groups, segments, stops](/docs/concepts/orders) — rate sheets attach to task groups, not orders. * [Roles and permissions](/docs/concepts/roles) — which roles can manage rate sheets and statements. * [Rate sheets (shippers)](/shippers/rate-sheets) — create and manage rate sheets as a shipper. * [Billing for forwarders](/forwarders/billing) — earn and pay through chrt. * [Billing for couriers](/couriers/billing) — get paid for the task groups you complete. > Rate sheets, line item groups, statements, and ledgers — the four objects that drive every charge on chrt.