driptab.yaml — GitOps billing configuration

driptab.yaml defines your billing catalog, metrics, add-ons, plans, webhooks, and dunning policy as code. Commit it to your repository and apply it with dtab sync.

Why driptab.yaml?

Instead of creating plans and catalog items one by one via the CLI or API, define your entire billing configuration in a single file. Benefits:

Version control: pricing changes are code changes with a reviewer and a diff.
Reproducibility: any environment (staging, prod) can be bootstrapped from the same file.
Review workflow: a price change goes through the same pull request process as code changes.
Agent-readable: AI agents can read the file to understand the billing structure.

Applying a configuration

dtab sync                    # applies driptab.yaml in the current directory
dtab sync path/to/driptab.yaml
dtab sync path/to/driptab.yaml --dry-run
dtab sync --dry-run          # shows what would change without applying

dtab sync is idempotent. Running it twice is safe — it upserts resources by code, it does not create duplicates.

dtab sync does not delete resources. If you remove a plan from driptab.yaml, it is not deleted from Driptab. Archive it explicitly if needed.

File structure

version: "1"
org: <org-slug>
workspace: <workspace-slug>
project: <project-slug>

catalog: [...]
metrics: [...]
addons: [...]
plans: [...]
dunning: { ... }
webhooks: [...]

All sections are optional. Sections not present in the file are not modified.

catalog

A list of pricing reference items. Each item defines a named, priced product.

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

  - code: vps.cx11
    name: "VPS CX11 — 2 vCPU / 4 GB / 40 GB SSD"
    amount_cents: 415
    currency: USD
    metadata: { vcpu: 2, ram_gb: 4, disk_gb: 40 }

Field	Required	Description
`code`	Yes	Stable key. Lowercase, digits, dots, dashes. `[a-z0-9._-]+`
`name`	Yes	Display name
`amount_cents`	Yes	Price in smallest currency unit (cents, pence, etc.)
`currency`	No	ISO-4217. Defaults to `USD`.
`metadata`	No	Free-form key-value pairs

code is the stable key for upserts. Changing code creates a new item.

metrics

A list of billable metric definitions.

metrics:
  - code: mail_out
    name: "Outbound Emails"
    aggregation_type: sum
    field_name: count

  - code: api_calls
    name: "API Calls"
    aggregation_type: count

Field	Required	Description
`code`	Yes	Stable key used in event payloads
`name`	Yes	Display name
`aggregation_type`	Yes	`sum`, `count`, `count_unique`, `max`, `latest`
`field_name`	Conditional	Required for `sum`, `max`, `count_unique`

Use metrics: [] (empty array) if your plans use only flat-fee charges.

addons

One-time charge definitions.

addons:
  - code: domain-transfer-com
    name: ".com Transfer"
    catalog_ref: tld.com.transfer
    invoice_timing: immediate

  - code: setup-fee
    name: "Onboarding Setup Fee"
    amount_cents: 9900
    currency: USD
    invoice_timing: immediate

Field	Required	Description
`code`	Yes	Stable key
`name`	Yes	Display name
`catalog_ref`	Conditional	Catalog item code to pull price from
`amount_cents`	Conditional	Direct price (if no `catalog_ref`)
`currency`	No	ISO-4217. Defaults to `USD`.
`invoice_timing`	No	Always `immediate` for add-ons

plans

Plan and charge definitions.

plans:
  - code: domain-register-com
    name: ".com Register"
    description: "Annual .com domain registration"
    interval: yearly
    amount_cents: 0
    currency: USD
    charges:
      - type: flat_fee
        catalog_ref: tld.com.register
        invoice_timing: immediate

  - code: vps-cx11-monthly
    name: "VPS CX11 Monthly"
    interval: monthly
    amount_cents: 0
    currency: USD
    charges:
      - type: flat_fee
        catalog_ref: vps.cx11
        invoice_timing: arrears

  - code: starter
    name: "Starter"
    interval: monthly
    amount_cents: 0
    currency: USD
    charges:
      - type: standard
        metric_ref: mail_out
        rate: "0.002"
        invoice_timing: arrears

Plan fields:

Field	Required	Description
`code`	Yes	Stable key
`name`	Yes	Display name
`description`	No	Optional longer description
`interval`	Yes	`weekly`, `monthly`, `quarterly`, `semiannual`, `yearly`
`amount_cents`	No	Base recurring fee. Defaults to `0`.
`currency`	Yes	ISO-4217
`charges`	No	List of charges

Charge fields:

Field	For type	Description
`type`	both	`flat_fee` or `standard`
`catalog_ref`	`flat_fee`	Catalog item code
`metric_ref`	`standard`	Billable metric code
`rate`	`standard`	Per-unit price as decimal string
`invoice_timing`	both	`immediate` or `arrears`
`amount_override_cents`	`flat_fee`	Override catalog price for this charge
`quantity_from`	`flat_fee`	Derive quantity from subscription property, e.g. `subscription_property.node_count`

dunning

Dunning policy — overdue invoice escalation steps.

dunning:
  enabled: true
  steps:
    - days_after_due: 3
      webhook_event: invoice.payment_overdue_reminder_1
    - days_after_due: 7
      webhook_event: invoice.payment_overdue_reminder_2
    - days_after_due: 14
      webhook_event: subscription.suspend_requested
    - days_after_due: 30
      webhook_event: subscription.terminate_requested

Driptab fires the specified webhook event at each step. Your system acts on the event. See Webhooks for the dunning pattern.

webhooks

Webhook endpoint registrations.

webhooks:
  - url: https://app.example.com/hooks/driptab
    events:
      - invoice.created
      - payment.succeeded
      - subscription.terminate_requested

dtab sync registers any new endpoints and updates existing ones (matched by URL). It does not delete endpoints removed from the file.

Complete example

See docs/examples/hostco.yaml for a complete, annotated example covering TLD domain registration plans, VPS flat-fee plans, Kubernetes node-count charges, transfer add-ons, dunning policy, and webhook endpoints.