Billing model

This page explains the vocabulary Driptab uses. Understanding these concepts is the prerequisite for every API call.

Plans

A plan is a priced, recurring package. Customers subscribe to plans; subscriptions drive invoice generation.

Key fields:

Field	Description
`code`	Stable machine identifier, e.g. `vps-cx11-monthly`. Used in API calls and driptab.yaml.
`name`	Human-readable label.
`interval`	Billing period: `weekly`, `monthly`, `quarterly`, `semiannual`, or `yearly`.
`amount_cents`	Base recurring fee in the smallest currency unit. Use `0` for pure usage-based plans.
`amount_currency`	ISO-4217 code, e.g. `USD`.
`charges`	Array of charges that generate invoice line items.

A plan with amount_cents: 0 and no charges is valid — useful as a free tier.

Charges

A charge is a pricing rule attached to a plan. Each charge produces one line item on the invoice. There are two models:

Standard (usage-based)

Linked to a billable metric. The charge multiplies the aggregated metric value by a per-unit rate.

{
  "charge_model": "standard",
  "billable_metric_id": "uuid-of-metric",
  "invoice_timing": "arrears",
  "properties": { "amount": "0.0015" }
}

The properties.amount is a decimal string representing the per-unit price in the plan's currency. Never a float.

Flat fee

Linked to a catalog item. The charge invoices the catalog item's price (or an override) regardless of usage.

{
  "charge_model": "flat_fee",
  "catalog_item_code": "vps.cx11",
  "invoice_timing": "arrears"
}

Flat-fee charges can also carry:

amount_override_cents — overrides the catalog item price for this charge.
quantity_formula — drives quantity from a subscription property (e.g. node count).

Invoice timing

Every charge has an invoice_timing:

immediate — invoiced at the start of the period. Use for anything paid in advance: domain registrations, annual subscriptions, committed resources.
arrears — invoiced at the end of the period. Use for anything billed after use: VPS compute, email volume, API calls.

The invoice timing controls when the line item appears on an invoice, not when the subscription starts.

Billable metrics

A billable metric defines what to measure and how to aggregate raw events.

Field	Description
`code`	Stable identifier used in event payloads, e.g. `mail_out`.
`aggregation_type`	How to aggregate: `sum`, `count`, `count_unique`, `max`, `latest`.
`field_name`	Which event property to aggregate (for `sum`, `max`, `count_unique`).

sum — add all field_name values in the period. Use for bytes, messages, API calls.
count — count the number of events, ignoring value. Use for actions.
count_unique — count distinct values of field_name. Use for unique users, unique IPs.
max — peak value in the period. Use for high-water-mark billing (storage).
latest — most recent value in the period. Use for seat-based billing.

Catalog items

A catalog item is a named, priced product in your project's pricing reference table.

catalog:
  - code: tld.com.register
    name: ".com Registration"
    amount_cents: 1200
    currency: USD
    metadata: { tld: com, operation: register }

Catalog items are referenced by flat_fee charges and by add-ons. Using a catalog separates pricing definitions from plan structure: when you change a price, you update the catalog item once; all future invoices for plans that reference it pick up the new price. Issued invoices are unaffected because pricing is snapshotted at invoice time.

Catalog items are project-scoped and managed via driptab.yaml + dtab sync or directly through the API.

Add-ons

An add-on is a one-time charge applied to a customer outside of the subscription cycle. Add-ons generate an immediate invoice when applied.

Common uses:

Domain transfer fee
Professional services
One-time setup charge
Overage for a previous period

Add-ons are defined at the project level and applied per customer:

dtab addons apply domain-transfer-com --customer cust_abc123

An add-on may reference a catalog item (to inherit its price) or carry its own amount_cents. The price is snapshotted when the add-on is applied, so catalog price changes after application do not affect the issued invoice.

Organization hierarchy

Resources in Driptab are scoped:

organization
  └── workspace
        └── project
              ├── catalog_items
              ├── billable_metrics
              ├── plans (with charges)
              ├── add_ons
              ├── customers (with subscriptions)
              └── webhook_endpoints

API requests include an X-Project-Id header to scope all operations to a specific project. A token authenticates to an organization; the project header narrows the scope.

What happens at period close

When a subscription's billing period ends:

The SubscriptionMeter Durable Object alarm fires.
Aggregated metric counters are read for the closing period.
Fees are computed: base plan fee + one fee per charge.
An invoice is written to D1 atomically with its fee line items.
The period rolls forward; counters reset; next alarm is scheduled.
A invoice.created webhook fires.

The invoice is immutable from this point. Pricing is snapshotted into each fee row so later plan or catalog changes cannot alter it.