ClassifiedBilling API

The ClassifiedBilling API lets you read and manage invoices, customers, and workspaces programmatically. It works as a standard REST API, as an MCP server for Claude AI, and is compatible with any AI platform or custom application that supports HTTP tool calling.

This documentation covers everything — from getting your first API key to calling every available tool, handling errors, and integrating with Claude's connector directory.

Quick Start

Get up and running in under 5 minutes.

1. Create an account

   Sign up at app.classifiedbilling.com. Any plan works — all plans include API access.
2. Generate an API key

   Go to Settings → API Keys in the left sidebar. Click New Key, give it a name, and copy your key — it starts with cb_live_ and is shown only once.
3. Make your first request

   Call the MCP server with your key in the Authorization header.
4. Handle the response

   All responses are JSON. Successful responses include a result field. Errors include an error field.

copy"syn-cmt">// Your first API call — list all workspaces
const response = await fetch('https:"syn-cmt">//app.classifiedbilling.com/api/mcp-server', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer cb_live_YOUR_KEY_HERE',
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    tool:  'list_workspaces',
    input: {}
  })
});

const data = await response.json();
console.log(data.result.workspaces);

copy# Same request with curl
curl -X POST https:"syn-cmt">//app.classifiedbilling.com/api/mcp-server \
  -H "Authorization: Bearer cb_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"tool":"list_workspaces","input":{}}'

Authentication

All API requests require a Bearer token in the Authorization header. ClassifiedBilling supports two types of tokens:

API Keys (recommended for custom apps)

API keys start with cb_live_ and are generated from your Settings page. They are long-lived and scoped to the user who created them.

copyAuthorization: Bearer cb_live_xK9mTz2pQrLvWnYs8dFgHj3a4BcDeF

OAuth Access Tokens (for Claude and third-party apps)

OAuth tokens are issued after a user completes the authorization flow. They expire after 90 days and are used by Claude and other AI platforms.

copyAuthorization: Bearer a3f8c9d2e1b4f7a6c5d8e2f1a9b3c6d4e7f2a5b8c1d4e7f3a6b9c2d5e8f1

Base URL

All API requests go to the same single endpoint. The tool field in the request body specifies which operation to perform.

copyhttps:"syn-cmt">//app.classifiedbilling.com/api/mcp-server

Request format

All requests are POST with a JSON body containing two fields:

Response format

All successful responses return a result object. All error responses return an error string.

copy"syn-cmt">// Success response
{
  "result": {
    "workspaces": [...],
    "total": 3
  }
}

"syn-cmt">// Error response
{
  "error": "Workspace not found or access denied."
}

Error Handling

ClassifiedBilling uses standard HTTP status codes. Always check both the status code and the error field in the response body.

copy"syn-cmt">// Recommended error handling pattern
const res = await fetch('https:"syn-cmt">//app.classifiedbilling.com/api/mcp-server', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ tool: 'list_invoices', input: { workspace_id: '...' } })
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`API error ${res.status}: ${error}`);
}

const { result } = await res.json();
"syn-cmt">// use result...

Rate Limits

API requests are limited per user to prevent abuse. Current limits:

When you exceed a rate limit you will receive a 429 Too Many Requests response. Wait before retrying.

MCP Overview

ClassifiedBilling implements the Model Context Protocol (MCP) — an open standard for connecting AI models to external tools and data. This means Claude (and any other MCP-compatible AI) can call your billing data directly in conversation.

Connecting Claude

To connect ClassifiedBilling to Claude AI:

1. Generate an API key

   Go to Settings → API Keys and create a new key. Name it something like "Claude AI".
2. Open Claude's connector page

   In Claude.ai, go to Customize → Connectors and find ClassifiedBilling in the directory.
3. Click Connect and paste your key

   You will be redirected to app.classifiedbilling.com/mcp-connect. Paste your cb_live_... key and click Approve.
4. Start using it

   Ask Claude: "Show my overdue invoices" or "How much revenue did I collect this month?"

List Workspaces

Returns all workspaces owned by the authenticated user. Call this first — you need a workspace_id for most other tools.

copy{
  "tool":  "list_workspaces",
  "input": {}
}

copy{
  "result": {
    "workspaces": [
      {
        "id":               "clx1a2b3c4d5e6f7g8h9",
        "title":            "SaaS Clerk",
        "description":      "My main billing workspace",
        "workspaceUrlSlug": "saas-clerk",
        "businessDetails": {
          "businessName":  "SaaS Clerk Ltd",
          "businessEmail": "hello@saasclerk.com"
        }
      }
    ]
  }
}

Workspace Summary

Returns customer count, invoice count, service item count, team member count, and a breakdown of invoices by payment status.

copy{
  "tool":  "get_workspace_summary",
  "input": { "workspace_id": "clx1a2b3c4d5e6f7g8h9" }
}

copy{
  "result": {
    "id":      "clx1a2b3c4d5e6f7g8h9",
    "title":   "SaaS Clerk",
    "business": "SaaS Clerk Ltd",
    "counts": {
      "customers":    12,
      "invoices":     38,
      "serviceItems": 6,
      "teamMembers":  2
    },
    "invoices_by_status": [
      { "status": "Paid", "count": 30 },
      { "status": "Due",  "count": 8  }
    ]
  }
}

List Customers

Returns customers in a workspace. Optionally filter by name or email using the search parameter. Returns up to 50 results.

copy{
  "tool": "list_customers",
  "input": {
    "workspace_id": "clx1a2b3c4d5e6f7g8h9",
    "search":       "acme"  "syn-cmt">// optional
  }
}

copy{
  "result": {
    "customers": [
      {
        "id":                        "cust_abc123",
        "companyName":               "Acme Corp",
        "companyEmail":              "billing@acme.com",
        "companyCurrency":           "USD",
        "companyCountry":            "United States",
        "companyContactFirstName":   "John",
        "companyContactLastName":    "Smith",
        "companyContactPersonEmail": "john@acme.com"
      }
    ],
    "total": 1
  }
}

Create Customer

Creates a new customer in a workspace. All address and contact fields are required.

copy{
  "tool": "create_customer",
  "input": {
    "workspace_id":       "clx1a2b3c4d5e6f7g8h9",
    "company_name":       "Acme Corp",
    "company_email":      "billing@acme.com",
    "currency":           "USD",
    "contact_first_name": "John",
    "contact_last_name":  "Smith",
    "contact_email":      "john@acme.com",
    "address":            "123 Main Street",
    "city":               "New York",
    "state":              "NY",
    "zip":                "10001",
    "country":            "United States"
  }
}

List Invoices

Returns invoices for a workspace. Filter by payment status and control how many results to return.

copy{
  "tool": "list_invoices",
  "input": {
    "workspace_id": "clx1a2b3c4d5e6f7g8h9",
    "status":       "Due",
    "limit":        10
  }
}

copy{
  "result": {
    "invoices": [
      {
        "id":       "inv_xyz789",
        "number":   "INV-0042",
        "client":   "Acme Corp",
        "amount":   2500.00,
        "currency": "USD",
        "status":   "Due",
        "issued":   "2025-02-01T00:00:00.000Z",
        "due":      "2025-03-01T00:00:00.000Z"
      }
    ],
    "total": 1
  }
}

Get Overdue Invoices

Returns all unpaid invoices where the due date has already passed. Results are ordered by oldest due date first — the most urgent first.

copy{
  "tool":  "get_overdue_invoices",
  "input": { "workspace_id": "clx1a2b3c4d5e6f7g8h9" }
}

copy{
  "result": {
    "overdue_invoices": [
      {
        "id":       "inv_xyz789",
        "number":   "INV-0042",
        "client":   "Acme Corp",
        "due_date": "2025-03-01T00:00:00.000Z",
        "amount":   2500.00,
        "currency": "USD"
      }
    ],
    "total_overdue_amount": 7850.00,
    "count": 3
  }
}

Mark Invoice as Paid

Updates an invoice's status to Paid and records the payment date and method.

copy{
  "tool": "mark_invoice_paid",
  "input": {
    "workspace_id":   "clx1a2b3c4d5e6f7g8h9",
    "invoice_id":     "inv_xyz789",
    "payment_method": "Bank Transfer"
  }
}

Revenue Summary

Returns total paid revenue, total outstanding, and invoice counts for a workspace. Useful for dashboard-style overviews.

copy{
  "tool":  "get_revenue_summary",
  "input": { "workspace_id": "clx1a2b3c4d5e6f7g8h9" }
}

copy{
  "result": {
    "total_paid":        18500.00,
    "total_outstanding": 7850.00,
    "paid_invoices":     12,
    "unpaid_invoices":   4,
    "total_invoices":    16
  }
}

OAuth 2.0 Flow

For third-party platforms (like Claude) that need to act on behalf of a user, ClassifiedBilling implements the OAuth 2.0 Authorization Code flow with PKCE.

Flow overview

copyYour app  →  redirect user to /mcp-connect?redirect_uri=...&state=...&code_challenge=...
User      →  pastes their ClassifiedBilling API key and clicks Approve
CB server →  redirects back to redirect_uri?code=...&state=...
Your app  →  POST /api/mcp-token with code + code_verifier
CB server →  returns { access_token, token_type, expires_in }
Your app  →  use access_token as Bearer token on all future API calls

Authorization endpoint

copyGET https:"syn-cmt">//app.classifiedbilling.com/mcp-connect
  ?redirect_uri=https:"syn-cmt">//yourapp.com/callback
  &state=RANDOM_STATE_STRING
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &client_id=your_app_name

Token endpoint

copyPOST https:"syn-cmt">//app.classifiedbilling.com/api/mcp-token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=CODE_FROM_CALLBACK
&redirect_uri=https:"syn-cmt">//yourapp.com/callback
&code_verifier=YOUR_ORIGINAL_VERIFIER

Returns:

copy{
  "access_token": "a3f8c9d2e1b4...",
  "token_type":   "Bearer",
  "expires_in":   7776000  "syn-cmt">// 90 days in seconds
}