Introduction

Get started with the Lucius Billing API for usage-based and subscription billing.

The Lucius Billing API powers the Contract-to-Cash (C2C) billing engine. It lets you programmatically submit usage events, query contracts and their pricing programs, and retrieve invoices with line items.

Who is this for?

If you have a Lucius contract with usage-based pricing, you'll use this API to report metered usage from your systems. Lucius rates each event against your pricing program, updates draft invoices in real time, and handles subscription charges automatically.

What can you do?

Resource	Actions
Customers	Create a customer (optional `external_id`), list / look up by your id
Usage events	Submit metered usage (bulk), list events, get event by ID
Contracts	Create a sample test contract, list contracts, inspect pricing, add usage rules
Invoices	List invoices, get invoice detail with line items

How it works

Your system submits usage → Lucius rates it → Invoice updated

Submit usage — POST events with a metric, quantity (volume), and optional fee_amount (your calculated fee)
Automatic rating — fee_amount if present, else applied_rate × quantity, else the contract usage rule
Invoice projection — The matching draft invoice is updated with the new charge
Billing cycle — At period end, invoices include both subscription and usage charges

Metrics are per contract, not a global list. See Usage events.

A customer is not a contract. Create one in the dashboard or POST /v1/billing/customers (pass external_id for your own id — we do not match by name). Then POST /v1/billing/contracts with the returned Lucius id as customer_id. See Customers and Quickstart.

Base URL

https://api.lucius.finance

Sandbox / UAT: https://api-dev.lucius.finance (dashboard: https://app-dev.lucius.finance).

All endpoints are under /v1/billing.

Next steps

MCP Server — Connect Claude Code, Cursor, or Codex to your Lucius data
Quickstart — Submit your first usage event in 5 minutes
Customers — Create a customer and store your external_id
Usage events — Metrics, fee_amount, and rating priority
Authentication — Set up your API key
API Reference — Full endpoint documentation