Billing & Usage¶

The billing system tracks resource usage at hourly granularity per project and product, generates monthly invoices, and manages payment methods through Stripe.

Endpoints¶

Method	Path	Description
`GET`	`/billing/usage?organization_id=<uuid>`	Get usage data for a period
`GET`	`/subscriptions`	List subscriptions
`GET`	`/subscriptions/{id}`	Show a subscription
`GET`	`/invoices`	List invoices
`GET`	`/invoices/{id}`	Show invoice with line items
`GET`	`/organizations/{id}/invoices`	List EasyBill invoices
`GET`	`/organizations/{id}/invoices/{invoice_id}`	Show EasyBill invoice
`GET`	`/organizations/{id}/invoices/download?invoice_id=<id>`	Download invoice PDF
`GET`	`/organizations/{id}/payment_methods`	List payment methods
`POST`	`/organizations/{id}/payment_methods/create_and_attach`	Attach a Stripe payment method
`PUT`	`/organizations/{id}/payment_methods/{payment_method_id}/set_default`	Set default payment method
`DELETE`	`/organizations/{id}/payment_methods/{payment_method_id}`	Remove a payment method

Usage data¶

GET /billing/usage?organization_id=<uuid>&from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z
Authorization: Bearer <token>

Returns resource consumption broken down by project and product for the requested window. Use this to build cost forecasts and chargeback reports.

Subscriptions¶

Subscriptions link a product to a project with a start (and optional end) date. Hourly usage entries are recorded against active subscriptions.

GET /subscriptions
Authorization: Bearer <token>

Subscription fields:

Field	Description
`id`	Subscription UUID
`organization_id`	Organization UUID
`project_id`	Project UUID (nullable — org-level subscriptions have none)
`product_id`	Product UUID
`start_date`	ISO 8601 datetime the subscription began
`end_date`	ISO 8601 datetime the subscription ended; `null` if active

Invoices¶

The platform generates two invoice representations:

Internal invoices (/invoices) reflect the platform's usage metering:

GET /invoices/{id}
Authorization: Bearer <token>

Fields: period, total (Money object: {cents, currency_iso}), and items (array of line items with product, project, unit price, and unit).

EasyBill invoices (/organizations/{id}/invoices) are the legally binding invoices delivered via the EasyBill integration. Download a PDF:

GET /organizations/{id}/invoices/download?invoice_id=<id>
Authorization: Bearer <token>

Returns application/pdf.

Payment methods¶

Payment methods are Stripe payment instruments attached to an organization.

GET /organizations/{id}/payment_methods
Authorization: Bearer <token>

Payment method fields:

Field	Description
`id`	Internal UUID
`payment_type`	`card`, `sepa_debit`, etc.
`default`	Whether this is the default payment method
`brand`	Card brand (e.g. `visa`); `null` for non-card methods
`last4`	Last four digits of the card number
`exp_month` / `exp_year`	Card expiry
`iban`	IBAN (SEPA debit only)

Attach a payment method¶

Use the Stripe.js PaymentElement in the dashboard to collect card details and generate a Stripe paymentMethodId, then attach it:

POST /organizations/{id}/payment_methods/create_and_attach
Authorization: Bearer <token>
Content-Type: application/json

{ "payment_method_id": "pm_..." }

Create a Stripe payment intent (for setup flow)¶

POST /organizations/{id}/payment_methods/payment_intent
Authorization: Bearer <token>

Returns { "client_secret": "seti_...secret_..." } for use with Stripe.js confirmSetup.

Authorization¶

Billing read operations require the billing:read permission. Update operations (setting default, removing a payment method) require billing:update. See RBAC Presets for which roles carry these permissions.