driptab/Docs
API

Getting started

This guide walks through the minimum steps to have Driptab billing a customer: install the CLI, authenticate, create a plan, subscribe a customer, ingest a usage event, and view the resulting invoice.

Prerequisites

  • Node.js 18+ installed.
  • A Driptab deployment (self-hosted via Wrangler or the hosted service).
  • An API token. If you are bootstrapping a fresh deployment, see the organization setup section in AGENTS.md.

Step 1 — Install the CLI

npm install -g @dotlabshq/dtab

Verify:

dtab --version

Step 2 — Authenticate

dtab token set dtab_f36951fb6dd443babd9df35d32ae1e0f

The token is stored in ~/.dtab/config.json.

Set your working context (org / workspace / project):

dtab use acme/default/billing

Verify:

dtab whoami

Expected output:

token   dtab_f36951fb…
api     https://driptab-api.example.com
context acme / default / billing

Step 3 — Create a billable metric (for usage-based plans)

Skip this step if your plan uses only flat-fee charges.

dtab metrics create \
  --code api_calls \
  --name "API Calls" \
  --aggregation-type count

dtab metrics list

CODE       NAME       AGG     FIELD   CREATED
api_calls  API Calls  count   —       Jun 8 2026

Note the metric ID from the output.

Step 4 — Create a plan

Usage-based plan (pay per API call):

dtab plans create \
  --code api-metered \
  --name "API Metered" \
  --interval monthly \
  --amount 0 \
  --currency USD

Add a charge to it:

dtab plans add-charge <plan_id> \
  --model standard \
  --metric <metric_id> \
  --rate 0.0015 \
  --timing arrears

Flat-fee plan (fixed monthly price):

dtab plans create \
  --code pro-monthly \
  --name "Pro Monthly" \
  --interval monthly \
  --amount 2900 \
  --currency USD

Verify:

dtab plans list
dtab plans get <plan_id>

Step 5 — Create a customer

dtab cust create \
  --external-id acme-user-1234 \
  --name "Jane Smith" \
  --email jane@acme.com \
  --currency USD

The --external-id is your system's stable identifier for this customer. Use it in all subsequent calls as ext:<external_id> instead of storing Driptab's UUID.

Step 6 — Start a subscription

dtab subs create \
  --external-id acme-sub-1234 \
  --customer ext:acme-user-1234 \
  --plan api-metered

Driptab initialises the SubscriptionMeter Durable Object and schedules a period-close alarm at current_period_end.

Verify:

dtab subs get ext:acme-sub-1234

ID          ext:acme-sub-1234
STATUS      active
PLAN        API Metered
PERIOD      2026-06-08 → 2026-06-30

Step 7 — Ingest a usage event

dtab ev ingest \
  --transaction-id call_01HX4K2000001 \
  --subscription ext:acme-sub-1234 \
  --code api_calls \
  --value 1

Response:

{ "accepted": true, "duplicate": false }

Send the same event again — it is idempotent:

dtab ev ingest \
  --transaction-id call_01HX4K2000001 \
  --subscription ext:acme-sub-1234 \
  --code api_calls \
  --value 1

{ "accepted": true, "duplicate": true }

The counter is not incremented a second time.

Step 8 — View invoices

Invoices are generated automatically when the billing period closes. The DO alarm fires at current_period_end and writes the invoice to D1.

To see invoices:

dtab inv list

NUMBER        STATUS       TOTAL   ISSUED
INV-2026-0001 outstanding  $0.45   2026-07-01

dtab inv get INV-2026-0001

Step 9 — Record a payment

When your payment provider confirms payment:

dtab payments record \
  --invoice INV-2026-0001 \
  --amount 45 \
  --currency USD \
  --provider manual

The invoice status updates to succeeded.

What's next