---
title: Billtyme documentation
description: Set up sending companies and manage customers and invoice drafts through MCP, with a default sender and shared billing rules behind every operation.
lastModified: 2026-09-10
search:
  tags: [overview, architecture, api]
sidebar:
  label: Overview
---

Billtyme is an MCP-first invoicing system. [Connect through MCP](/docs/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 foundation**
>
> The current `v0.1` API manages legal sender companies, company-scoped
> customers, and draft invoices. It does not render PDFs, allocate invoice
> numbers, issue invoices, or send email yet. The MCP interface exposes company
> management, customer, and invoice-draft tools once its endpoint and WorkOS
> integration are configured.

## 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](/reference) for request and response schemas.

## Architecture

```mermaid
flowchart LR
  A["Agents and integrations"] --> B["Hono + OpenAPI"]
  B --> C["Application commands"]
  C --> D["PlanetScale Postgres"]
  C -. "PDF artifacts — next" .-> E["Cloudflare R2"]
```

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

1. **Select or create the legal sender company**

    Use the company that owns the invoice identity, defaults, and future number
    series.

2. **Find or create the company-scoped customer**

    Filter the customer collection by a stable external reference, then persist
    validated billing data when absent.

3. **Create a draft invoice**

    Send exact line amounts and a stable idempotency key.

4. **Retrieve the draft**

    Review the persisted result before any future issuance command.

## Continue

- [MCP connection](/docs/mcp)
- [Authentication](/docs/authentication)
- [Invoices](/docs/invoices)
- [API reference](/reference)
- [Changelog](/changelog)

## Roadmap

> **Separate commands by design**
>
> The next commands will render a private PDF preview, record approval, issue
> with atomic numbering, and send. MCP will expose those workflows through the
> shared billing services as they become available.