---
title: Why Billtyme starts with an API
description: Why Billtyme keeps durable invoicing commands independent from Slack, web interfaces, and the future agents or MCP clients that invoke them.
type: blog
date: 2026-08-11
lastModified: 2026-08-12
authors: SkillSail
search:
  tags: [architecture, api, agents]
sidebar:
  label: Why API first
---

An agent-first product does not need to begin with an agent runtime. It needs a trustworthy set of commands that any agent can call.

For Billtyme, that means the invoicing system owns legal sender companies, customer records, draft calculations, authorization, idempotency, and audit history. Slack, SkillSail Operations, a small web interface, and a future MCP server are channels around that same core.

```mermaid
flowchart LR
  A["SkillSail Operations"] --> D["Billtyme command API"]
  B["Dedicated Slack agent — later"] --> D
  C["MCP adapter — later"] --> D
  D --> E["Application services"]
  E --> F["PlanetScale Postgres"]
  E -. "PDF artifacts — next" .-> G["Cloudflare R2"]
```

## Why state belongs in the billing core

A pure PDF generator can render a document, but it cannot safely answer the questions that matter after the first request:

- Which invoice numbers have already been issued?
- Which customer and billing address did the invoice snapshot?
- Was this command a retry or a new request?
- Who prepared, approved, issued, or sent the invoice?

Those facts need a durable, tenant-scoped system of record.

## The sequence matters

1. **Stabilize the HTTP contract**

    Start with narrow company, customer, and invoice commands described by
    OpenAPI.

2. **Add the legal invoice lifecycle**

    Render a private preview, record approval, allocate the invoice number
    atomically, then send.

3. **Add agent channels**

    Let SkillSail Operations and later a dedicated Billtyme agent call the same
    application services.

4. **Expose MCP when interoperability matters**

    Keep MCP as an adapter rather than a second implementation of invoicing
    rules.

> **The current boundary**
>
> Billtyme v0.1 manages legal sender companies, company-scoped customers, and
> draft invoices. PDF preview, numbering, issuance, sending, and MCP remain
> planned work.