driptab/Docs
API

driptab.yaml schema reference

Full field reference for driptab.yaml. Apply with dtab sync.

Top-level fields

Field Required Type Description
version Yes "1" Schema version. Must be "1".
org Yes string Organization slug
workspace Yes string Workspace slug
project Yes string Project slug
catalog No array Catalog item definitions
metrics No array Billable metric definitions
addons No array Add-on definitions
plans No array Plan definitions
dunning No object Dunning policy
webhooks No array Webhook endpoint registrations

Sections not present are not modified by dtab sync.

catalog[]

Each item represents a named, priced product in the pricing reference table.

Field Required Type Description
code Yes string Stable key. Pattern: [a-z0-9._-]+. Max 64 chars.
name Yes string Display name. Max 128 chars.
amount_cents Yes integer ≥ 0 Price in smallest currency unit
currency No string ISO-4217, 3 chars. Default: USD.
metadata No object Free-form key-value pairs. Stored as JSON.

code is the upsert key. Changing code creates a new item; the old one is not automatically archived.

Example:

catalog:
  - 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

metrics[]

Field Required Type Description
code Yes string Stable identifier used in event payloads
name Yes string Display name
aggregation_type Yes enum sum, count, count_unique, max, latest
field_name Conditional string Event property to aggregate. Required for sum, max, count_unique.

Example:

metrics:
  - code: storage_bytes
    name: "R2 Storage"
    aggregation_type: sum
    field_name: bytes

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

Use metrics: [] for flat-fee-only projects.

addons[]

Field Required Type Description
code Yes string Stable identifier
name Yes string Display name
description No string Optional description
catalog_ref Conditional string Catalog item code to inherit price from
amount_cents Conditional integer ≥ 0 Direct price. Required if no catalog_ref.
currency No string ISO-4217. Default: USD. Ignored if catalog_ref is set.
invoice_timing No enum Always immediate.

One of catalog_ref or amount_cents is required.

Example:

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

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

plans[]

Plan fields

Field Required Type Description
code Yes string Stable identifier
name Yes string Display name
description No string Optional description
interval Yes enum weekly, monthly, quarterly, semiannual, yearly
amount_cents No integer ≥ 0 Base recurring fee. Default: 0.
currency Yes string ISO-4217
charges No array Charge definitions

Charge fields (common)

Field Required Type Description
type Yes enum standard or flat_fee
invoice_timing No enum immediate or arrears. Default: arrears.
properties No object Additional charge properties

Charge fields for type: standard

Field Required Type Description
metric_ref Yes string Billable metric code
rate Yes string Per-unit price as decimal string, e.g. "0.0015"

Charge fields for type: flat_fee

Field Required Type Description
catalog_ref Conditional string Catalog item code
amount_override_cents No integer ≥ 0 Override catalog item price for this charge
quantity_from No string Derive quantity from subscription property. e.g. subscription_property.node_count

Examples:

plans:
  # Pure flat-fee, yearly, paid upfront
  - code: domain-register-com
    name: ".com Register"
    interval: yearly
    amount_cents: 0
    currency: USD
    charges:
      - type: flat_fee
        catalog_ref: tld.com.register
        invoice_timing: immediate

  # Monthly flat-fee, billed after use
  - 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

  # Yearly with price override (2 months free)
  - code: vps-cx21-yearly
    name: "VPS CX21 Yearly"
    interval: yearly
    amount_cents: 0
    currency: USD
    charges:
      - type: flat_fee
        catalog_ref: vps.cx21
        amount_override_cents: 8300
        invoice_timing: immediate

  # K8s nodes — quantity from subscription property
  - code: k8s-cx21-monthly
    name: "K8s Cluster CX21 Nodes"
    interval: monthly
    amount_cents: 0
    currency: USD
    charges:
      - type: flat_fee
        catalog_ref: k8s.node.cx21
        quantity_from: subscription_property.node_count
        invoice_timing: arrears

  # Usage-based with base fee
  - code: pro-monthly
    name: "Pro"
    interval: monthly
    amount_cents: 2900
    currency: USD
    charges:
      - type: standard
        metric_ref: mail_out
        rate: "0.001"
        invoice_timing: arrears
      - type: standard
        metric_ref: storage_bytes
        rate: "0.000005"
        invoice_timing: arrears

dunning

Field Required Type Description
enabled No boolean Enable dunning. Default: false.
steps Yes if enabled array List of escalation steps

dunning.steps[]

Field Required Type Description
days_after_due Yes integer ≥ 1 Days after invoice due date to fire the webhook
webhook_event Yes string Event code to fire

Valid webhook_event values for dunning steps: invoice.payment_overdue_reminder_1, invoice.payment_overdue_reminder_2, subscription.suspend_requested, subscription.terminate_requested.

Example:

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

webhooks[]

Field Required Type Description
url Yes string (URL) HTTPS endpoint to deliver events to
events Yes array of strings Event codes to subscribe to. Must be non-empty.

Valid event codes: invoice.created, invoice.payment_overdue_reminder_1, invoice.payment_overdue_reminder_2, subscription.period_renewed, subscription.suspend_requested, subscription.terminate_requested, addon.applied, payment.succeeded.

Example:

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

dtab sync registers new endpoints by URL. If an endpoint with the same URL already exists, its event subscription list is updated. Endpoints not present in the file are not deleted.