Billtyme documentation
Set up sending companies and manage customers and invoice drafts through MCP, with a default sender and shared billing rules behind every operation.
Billtyme is an MCP-first invoicing system. Connect through MCP to set up sending companies, edit their details, and manage customers and invoice drafts. Routine operations use your organization’s default sender automatically. The existing REST API remains available over the same billing services.
Current surface
| Capability | Endpoint |
|---|---|
| Service health | GET /health |
| OpenAPI 3.1 contract | GET /openapi.json |
| List/create companies | GET/POST /v1/companies |
| Get a company | GET /v1/companies/{company_id} |
| List/create customers | GET/POST /v1/companies/{company_id}/customers |
| Get a customer | GET /v1/companies/{company_id}/customers/{customer_id} |
| List/create invoices | GET/POST /v1/companies/{company_id}/invoices |
| Get an invoice | GET /v1/companies/{company_id}/invoices/{invoice_id} |
See the generated API reference for request and response schemas.
Architecture
The channel remains replaceable. Billtyme owns authorization, business rules, state, and audit history behind one contract.
Design principles
The API is the source of truth
Business rules live behind a typed command API. Slack and MCP are adapters, not alternate implementations of invoice logic.
State is durable
Accounts, companies, customers, invoices, idempotency records, and audit events belong in Postgres. A stateless PDF generator cannot safely allocate invoice numbers, remember customers, or support an invoice lifecycle.
Writes are safe to retry
Every write requires an Idempotency-Key. Repeating the same command with the same key returns the original result; reusing the key for a different request is rejected.
Tenant identity comes from authentication
Billtyme derives an internal account from the verified WorkOS org_id claim. That account ID and the WorkOS organization ID are never accepted from request input. Legal sender companies are resources inside the account and use explicit company_id path parameters.
One WorkOS organization/account can hold multiple companies. A user can also belong to multiple WorkOS organizations, so independently administered businesses remain separate without limiting parent-company portfolios.
Recommended agent flow
Select or create the legal sender company
Use the company that owns the invoice identity, defaults, and future number series.
Find or create the company-scoped customer
Filter the customer collection by a stable external reference, then persist validated billing data when absent.
Create a draft invoice
Send exact line amounts and a stable idempotency key.
Retrieve the draft
Review the persisted result before any future issuance command.