hdls Billing
hdls Billing is a headless, MCP-native subscriptions & billing backend. It manages customers, subscriptions, and invoices, operated entirely through named tools your AI assistant calls. It stands in for tools like Chargebee, Recurly — same job, no UI to run.
💬 Just ask
"Create an invoice for Acme for $2,000 and show me what's overdue."
You don't call these tools yourself — just tell your assistant in plain English. Everything below is the reference for when you (or your assistant) want the exact details.
How Billing is organized
The headline entity is the subscription — start there, then attach the rest to it. Records connect by reference: an invoice links to a customer and a subscription; an invoice_line links to an invoice and a plan. The billing_event table is an append-only timeline — every change and note lands there and is never edited or deleted.
| Entity | Purpose | Relates to |
|---|---|---|
subscription | A customer enrolled on a plan, tracking billing period and lifecycle status. | customer, plan |
customer | The billed party: holds billing identity, currency, running balance, and dunning status. | — |
plan | A priced, recurring offering (flat/per_unit/tiered/usage) that subscriptions reference. | — |
invoice | A billing document totalling line items for a customer, optionally tied to a subscription. | customer, subscription |
invoice_line | A single charge line on an invoice (subscription, usage, one_time, discount, tax, credit). | invoice, plan |
billing_event | Append-only audit log shared by customers, subscriptions, and invoices (polymorphic via entity_type/entity_id). | — |
Common workflows
Each line is one real sequence of tool calls — your assistant chains them for you.
- Set up a subscription end to end:
create_customer→start_subscription→record_usage
Tools
Call these at https://hdls.ai/api/mcp/billing. Required fields you must supply; optional fields refine the call. You never pass tenant_id — it is stamped server-side.
Create
| Tool | What it does | Required | Optional |
|---|---|---|---|
create_customer | Create a new customer. | name | email, company, status, currency, billing_address, tax_id |
Update & advance
| Tool | What it does | Required | Optional |
|---|---|---|---|
start_subscription | Start a subscription. | customer_id | plan_id, status, quantity, currency, current_period_start, current_period_end |
record_usage | Record a usage. | id | — |
issue_invoice | Issue an invoice. | customer_id | subscription_id, number, status, currency, subtotal, tax |
Find & read
| Tool | What it does | Required | Optional |
|---|---|---|---|
list_invoices | Search invoices by free-text and/or column filters (tenant-scoped, paginated). | — | search, filters, limit, orderBy |
Field lists come from the product's live schema and are embedded in each tool's own description — read the tool description for the exact, current fields.
Field reference
Every field you can set on each record. Custom fields you add live alongside these in data.
subscription
| Field | Type | Required | Notes |
|---|---|---|---|
customer_id | id | Yes | Links to a customer. |
plan_id | id | Links to a plan. | |
status | text | Lifecycle state. | |
quantity | numeric(14,3) | ||
currency | text | ||
current_period_start | timestamp | ||
current_period_end | timestamp | ||
trial_end | timestamp | ||
cancel_at | timestamp | ||
cancelled_at | timestamp | ||
data | json | Free-form JSON — custom fields live here. |
customer
| Field | Type | Required | Notes |
|---|---|---|---|
name | text | Yes | Display name. |
email | text | ||
company | text | ||
status | text | Lifecycle state. | |
currency | text | ||
billing_address | text | ||
tax_id | text | External identifier. | |
balance | numeric(14,2) | ||
data | json | Free-form JSON — custom fields live here. |
plan
| Field | Type | Required | Notes |
|---|---|---|---|
name | text | Yes | Display name. |
code | text | ||
description | text | ||
pricing_model | text | ||
interval | text | ||
amount | numeric(14,2) | ||
currency | text | ||
is_active | true / false | ||
data | json | Free-form JSON — custom fields live here. |
invoice
| Field | Type | Required | Notes |
|---|---|---|---|
customer_id | id | Yes | Links to a customer. |
subscription_id | id | Links to a subscription. | |
number | text | ||
status | text | Lifecycle state. | |
currency | text | ||
subtotal | numeric(14,2) | ||
tax | numeric(14,2) | ||
total | numeric(14,2) | ||
amount_paid | numeric(14,2) | ||
issued_at | timestamp | ||
due_at | timestamp | ||
paid_at | timestamp | ||
data | json | Free-form JSON — custom fields live here. |
invoice_line
| Field | Type | Required | Notes |
|---|---|---|---|
invoice_id | id | Yes | Links to an invoice. |
plan_id | id | Links to a plan. | |
description | text | Yes | |
line_type | text | ||
quantity | numeric(14,3) | ||
unit_amount | numeric(14,2) | ||
amount | numeric(14,2) | ||
period_start | timestamp | ||
period_end | timestamp | ||
data | json | Free-form JSON — custom fields live here. |
Tailor it with custom fields
Add fields without a schema change. add_custom_field defines one, list_custom_fields shows what's defined, and promote_custom_field (admin) shares a personal field with the whole workspace. The value lives in each row's data (JSON) and is set and read through the normal record tools. See Products, tools & custom fields for the full model.
Roles & safety
- Tenant isolation is automatic. Your credential is pinned to one workspace; you never pass
tenant_id, and you can only ever see your own data (enforced by Postgres row-level security). - Role-gated. Permissions run
reader < member < admin < owner. Installing a product and promoting a custom field workspace-wide need admin/owner. - History is append-only. The
billing_eventtimeline is never edited or deleted — it's your audit trail.
Connect
On the concierge (https://hdls.ai/api/mcp), run install_product({ slug: "billing" }) (admin/owner) to enable it for your workspace, then add https://hdls.ai/api/mcp/billing as a connector in your assistant — see Connect your assistant.
A worked example
The literal call your assistant makes when you ask it to create the headline record:
Tool: create_customer
Arguments: {
"name": "Acme Corp"
}