Billing API Reference

All Billing endpoints are served under the /api/v1/billing prefix via the gateway. Amounts are in cents (integer).

Endpoints

Items

Method	Path	Description
GET	/api/v1/billing/items	List items (filters below)
POST	/api/v1/billing/items	Create item
GET	/api/v1/billing/items/:id	Get item by ID
PUT	/api/v1/billing/items/:id	Update item
DELETE	/api/v1/billing/items/:id	Delete item
GET	/api/v1/billing/items/by-provider-ref	Find by provider reference (?provider=, ?providerRef=)

Item Filters: ?category=, ?provider=, ?service=, ?from=, ?to=, ?recurring=, ?tags=, ?limit=, ?stageApp=, ?author=

Categories

Method	Path	Description
GET	/api/v1/billing/categories	List all categories
POST	/api/v1/billing/categories	Create category
GET	/api/v1/billing/categories/:idOrName	Get category by ID or name
PUT	/api/v1/billing/categories/:id	Update category
DELETE	/api/v1/billing/categories/:id	Delete category

Reports

Method	Path	Description
GET	/api/v1/billing/reports/summary	Total spend and item count
GET	/api/v1/billing/reports/breakdown	Grouped spending (?by=provider|category|service|recurring|tag)
GET	/api/v1/billing/reports/trend	Spending over time (?interval=day|week|month)

Report Filters: ?category=, ?provider=, ?service=, ?from=, ?to=

Status

Method	Path	Description
GET	/api/v1/billing/status	Service status with storage stats

Search

Method	Path	Description
GET	/api/v1/billing/search?q=<term>	Full-text search across items (?limit=)

Sync

Method	Path	Description
POST	/api/v1/billing/sync	Trigger manual sync from a provider
GET	/api/v1/billing/sync/jobs	List sync job history (?provider=)
GET	/api/v1/billing/sync/jobs/:id	Get sync job details
GET	/api/v1/billing/sync/adapters	List registered sync adapters

Examples

Create a Billing Item

curl -X POST http://localhost:3000/api/v1/billing/items \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GCP Compute Engine",
    "amount": 1050,
    "currency": "USD",
    "provider": "gcp",
    "providerRef": "gcp-inv-2026-03",
    "tags": ["compute", "production"],
    "description": "March compute costs",
    "recurring": true,
    "period": "monthly"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "abc123def456",
    "name": "GCP Compute Engine",
    "amount": 1050,
    "currency": "USD",
    "provider": "gcp",
    "providerRef": "gcp-inv-2026-03",
    "tags": ["compute", "production"],
    "description": "March compute costs",
    "recurring": true,
    "period": "monthly",
    "date": "2026-03-05T12:00:00.000Z",
    "createdAt": "2026-03-05T12:00:00.000Z",
    "updatedAt": "2026-03-05T12:00:00.000Z"
  }
}

List Items with Filters

curl "http://localhost:3000/api/v1/billing/items?provider=gcp&from=2026-03-01&to=2026-03-31&limit=20"

Create a Category

curl -X POST http://localhost:3000/api/v1/billing/categories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Infrastructure",
    "description": "Cloud infrastructure costs",
    "color": "#4A90D9"
  }'

Get Spending Summary

curl "http://localhost:3000/api/v1/billing/reports/summary?from=2026-03-01&to=2026-03-31"

Response:

{
  "success": true,
  "data": {
    "totalAmount": 52500,
    "itemCount": 15,
    "currency": "USD",
    "from": "2026-03-01",
    "to": "2026-03-31"
  }
}

Get Spending Breakdown

curl "http://localhost:3000/api/v1/billing/reports/breakdown?by=provider"

Response:

{
  "success": true,
  "data": [
    { "key": "gcp", "amount": 35000, "count": 8, "percentage": 66.7 },
    { "key": "openai", "amount": 17500, "count": 7, "percentage": 33.3 }
  ]
}

Get Spending Trend

curl "http://localhost:3000/api/v1/billing/reports/trend?interval=month&from=2026-01-01"

Response:

{
  "success": true,
  "data": [
    { "date": "2026-01", "amount": 45000, "count": 12 },
    { "date": "2026-02", "amount": 48000, "count": 14 },
    { "date": "2026-03", "amount": 52500, "count": 15 }
  ]
}

Search Items

curl "http://localhost:3000/api/v1/billing/search?q=compute&limit=10"

Trigger a Sync

curl -X POST http://localhost:3000/api/v1/billing/sync \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gcp",
    "token": "<gcp-access-token>",
    "from": "2026-03-01",
    "to": "2026-03-31",
    "projectId": "my-gcp-project"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "xyz789ghi012",
    "provider": "gcp",
    "status": "completed",
    "itemsCreated": 5,
    "itemsUpdated": 2,
    "startedAt": "2026-03-05T12:00:00.000Z",
    "completedAt": "2026-03-05T12:00:05.000Z"
  }
}

Get Service Status

curl http://localhost:3000/api/v1/billing/status

Response:

{
  "success": true,
  "data": {
    "initialized": true,
    "config": { "version": 1, "currency": "USD" },
    "totalItems": 42,
    "totalCategories": 5,
    "totalSyncJobs": 3,
    "totalAmount": 150000,
    "currency": "USD",
    "storageType": "file"
  }
}

Response Envelope

All responses follow the standard envelope format:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Item not found: abc123def456"
  }
}