Billing API

Manage usage meters, pricing plans, invoices, and credits. All endpoints require superadmin authentication and are prefixed with /admin/billing.

Endpoints Overview

Usage Meters

Method	Endpoint	Description
GET	/admin/billing/meters	List all usage meters
POST	/admin/billing/meters	Create a usage meter
PATCH	/admin/billing/meters/{id}	Update a usage meter
DELETE	/admin/billing/meters/{id}	Delete a usage meter

Tier Prices

Method	Endpoint	Description
GET	/admin/billing/tier-prices	List tier prices
POST	/admin/billing/tier-prices	Create a tier price
PATCH	/admin/billing/tier-prices/{id}	Update a tier price
DELETE	/admin/billing/tier-prices/{id}	Delete a tier price

Pricing Plans

Method	Endpoint	Description
GET	/admin/billing/plans	List pricing plans
POST	/admin/billing/plans	Create a pricing plan
PATCH	/admin/billing/plans/{id}	Update a pricing plan
DELETE	/admin/billing/plans/{id}	Delete a pricing plan
POST	/admin/billing/plans/{id}/components	Add a component
PATCH	/admin/billing/plans/{id}/components/{cid}	Update a component
DELETE	/admin/billing/plans/{id}/components/{cid}	Remove a component
PUT	/admin/billing/plans/{id}/components/{cid}/buckets	Set usage tier buckets

Invoices

Method	Endpoint	Description
GET	/admin/billing/invoices	List invoices
GET	/admin/billing/invoices/{id}	Get invoice details
POST	/admin/billing/invoices/{id}/action	Transition invoice state
GET	/admin/billing/invoices/{id}/download	Download as HTML

Credits & Usage

Method	Endpoint	Description
POST	/admin/billing/instances/{id}/credits	Add credit adjustment
GET	/admin/billing/instances/{id}/balance	Get credit balance
GET	/admin/billing/instances/{id}/usage	Get usage summaries
GET	/admin/billing/instances/{id}/periods	List billing periods

---

Usage Meters

Create Meter

POST /admin/billing/meters

{
  "key": "api_calls",
  "label": "API Calls",
  "unit": "calls",
  "overage_rate_cents": 1,
  "currency": "USD",
  "rate_cadence": "monthly",
  "included_allowance_feature_key": "api_calls_included"
}

Field	Type	Required	Description
key	string	Yes	Unique identifier
label	string	Yes	Display name
unit	string	Yes	Unit label (e.g., "calls", "GB")
overage_rate_cents	integer	No	Cost per unit beyond allowance
currency	string	No	ISO currency code (default: USD)
rate_cadence	string	No	monthly or yearly
included_allowance_feature_key	string	No	Feature key for included allowance

Response: 201 Created with the meter object.

---

Pricing Plans

Create Plan

POST /admin/billing/plans

{
  "name": "Professional",
  "slug": "professional",
  "description": "For growing teams",
  "is_active": true,
  "components": [
    {
      "meter_key": "api_calls",
      "type": "metered",
      "included_quantity": 10000
    },
    {
      "type": "flat",
      "label": "Base Fee",
      "unit_price_cents": 9900
    }
  ]
}

Plans support nested components and usage tier buckets at creation time.

Set Usage Tier Buckets

PUT /admin/billing/plans/{plan_id}/components/{component_id}/buckets

[
  { "from_quantity": 0, "to_quantity": 10000, "unit_price_cents": 0 },
  { "from_quantity": 10001, "to_quantity": 100000, "unit_price_cents": 1 },
  { "from_quantity": 100001, "to_quantity": null, "unit_price_cents": 0.5 }
]

Replaces all existing buckets for the component.

---

Invoices

List Invoices

GET /admin/billing/invoices

Parameter	Type	Description
instance_id	uuid	Filter by tenant instance
status	string	Filter by status: draft, finalized, sent, paid, overdue, void

Transition Invoice

POST /admin/billing/invoices/{invoice_id}/action

{
  "action": "finalize"
}

Available actions: finalize, send, mark_paid, void.

Download Invoice

GET /admin/billing/invoices/{invoice_id}/download

Returns an HTML document suitable for printing or PDF conversion.

---

Credits

Add Credit

POST /admin/billing/instances/{instance_id}/credits

{
  "amount_cents": 5000,
  "description": "Promotional credit — Q1 2026"
}

Response: Returns the updated credit balance.

Get Balance

GET /admin/billing/instances/{instance_id}/balance

{
  "instance_id": "...",
  "balance_cents": 5000
}

---

Usage & Periods

Get Usage Summaries

GET /admin/billing/instances/{instance_id}/usage

Returns up to 100 usage summary records ordered by most recent period.

List Billing Periods

GET /admin/billing/instances/{instance_id}/periods

Returns all billing periods for an instance with start/end dates and status.

---

Related

• Marketplace API — Listing management endpoints
• Search API — Platform search endpoints