Billing and invoices

Billing plans, invoicing, metered usage, and subscription pricing.

Manual invoices via actions and tools are available today. Subscription billing plans are coming soon.

An invoice represents a request for payment, created from a completed checkout, a manual API call, or a recurring billing cycle. A billing plan defines a recurring pricing structure (subscriptions, metered usage, tiered pricing) that issues invoices automatically over time.

How to use

Invoices and billing are a standalone primitive. You can use them as part of the Colossal platform — invoices issued automatically from a checkout and billed to a customer — or drop them into an existing platform to handle subscriptions, metered usage, and recurring billing on top of your own product and customer data.

Where to use

Actions

3 actions for fetching, creating, and adding line items to invoices.

Tools

LLM-callable tools for invoice creation and line item management.

Billing plans

A billing plan defines a recurring pricing structure for subscriptions and usage-based billing. Plans support pay-per-usage (e.g. API calls or AI tokens), per-seat pricing, flat monthly subscriptions, tiered pricing with volume discounts, package-based bundles, and hybrid models that combine a base fee with metered overages.

Plans support pro-rating by default, so mid-cycle changes are handled automatically.

Plan features

Features are defined at the project level. Each feature has a unique key, a human-readable name, and an optional link to a usage meter for metered billing. Features without a meter represent static entitlements (e.g. “access to premium support”). Features with a meter track consumption and feed into usage-based pricing.

Usage meters

A usage meter tracks consumption events for a specific feature. Each meter has an aggregation type (COUNT, SUM, MAX, MIN, LATEST, or UNIQUE_COUNT) that controls how events roll up within a billing cycle.

Rate cards

Rate cards connect a plan to a feature with specific pricing. A plan can have multiple rate cards, one per feature. Four pricing structures are supported.

• Flat. Fixed amount per cycle.
• Linear. Per-unit price.
• Package. Price per bundle of N units.
• Tiered. Graduated pricing based on usage.

Each rate card has a payment timing (cycle_start or cycle_end), an optional allowance (number of free units per interval), and a flag for whether usage above the allowance is blocked or billed as overage.

Invoice lifecycle

draft

Being assembled. Not yet finalized.

open

Issued to the customer and awaiting payment.

partially_paid

Some but not all of the balance has been collected.

paid

Fully settled.

void

Cancelled. Will not be collected.

The source field records how the invoice was created: checkout (from a completed checkout session), manual (via the API or dashboard), or subscription (from a recurring billing cycle).

Related objects

• Checkout and payments. Invoices are issued from completed checkouts.
• Customers. Invoices are billed to a customer.
• Projects. Manage billing settings at the project level.