> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colossal.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing and invoices

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

<Note>Manual invoices via actions and tools are available today. Subscription billing plans are *coming soon*.</Note>

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](/concepts/checkout-and-payments) and billed to a [customer](/concepts/customers) — or drop them into an existing platform to handle subscriptions, metered usage, and recurring billing on top of your own product and customer data.

## Surfaces

<CardGroup cols={3}>
  <Card title="Events" icon="bolt" href="/apps/colossal-app/events#invoices">
    Events for invoice creation and payment.
  </Card>

  <Card title="Actions" icon="play" href="/apps/colossal-app/actions#invoices">
    3 actions for fetching, creating, and adding line items to invoices.
  </Card>

  <Card title="Tools" icon="sparkles" href="/apps/colossal-app/tools#invoices">
    LLM-callable tools for invoice creation and line item management.
  </Card>
</CardGroup>

## 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, AI tokens, or shared usage credits for chat, the storefront builder, and image generation), 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. Colossal uses this pattern for shared usage credits across AI-heavy surfaces.

### 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

<AccordionGroup>
  <Accordion title="draft" icon="pen-line">
    Being assembled. Not yet finalized.
  </Accordion>

  <Accordion title="open" icon="envelope-open">
    Issued to the customer and awaiting payment.
  </Accordion>

  <Accordion title="partially_paid" icon="circle-half-stroke">
    Some but not all of the balance has been collected.
  </Accordion>

  <Accordion title="paid" icon="circle-check">
    Fully settled.
  </Accordion>

  <Accordion title="void" icon="ban">
    Cancelled. Will not be collected.
  </Accordion>
</AccordionGroup>

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](/concepts/checkout-and-payments). Invoices are issued from completed checkouts.
* [Customers](/concepts/customers). Invoices are billed to a customer.
* [Projects](/concepts/projects). Manage billing settings at the project level.