Quickstart
Submit your first usage event and see it on an invoice in 5 minutes.
This guide walks you through the complete flow: list your contracts, inspect pricing, submit a usage event, and verify it appears on the invoice.
Prerequisites
- A Lucius API key (create one in Settings > API Keys in the dashboard)
- An active C2C contract with usage-based pricing
Step 1: List your contracts
Verify your contract is active and check which metrics it accepts.
curl https://api.lucius.finance/v1/billing/contracts \
-H "Authorization: Bearer luc_live_YOUR_KEY"const res = await fetch("https://api.lucius.finance/v1/billing/contracts", {
headers: { Authorization: "Bearer luc_live_YOUR_KEY" },
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
"https://api.lucius.finance/v1/billing/contracts",
headers={"Authorization": "Bearer luc_live_YOUR_KEY"},
)
print(res.json())Response:
{
"object": "list",
"data": [
{
"object": "contract",
"id": "acme-corp-2026",
"customer_name": "Acme Corp",
"status": "active",
"currency": "USD",
"billing_cadence": "monthly",
"metrics": ["revenue_amount_invoiced"]
}
],
"has_more": false,
"total_count": 1
}Note the id and metrics fields — you'll need them to submit usage.
Step 2: Check pricing
See how your usage will be rated.
curl https://api.lucius.finance/v1/billing/contracts/acme-corp-2026/pricing \
-H "Authorization: Bearer luc_live_YOUR_KEY"const res = await fetch(
"https://api.lucius.finance/v1/billing/contracts/acme-corp-2026/pricing",
{ headers: { Authorization: "Bearer luc_live_YOUR_KEY" } },
);
const pricing = await res.json();
console.log(pricing.rules);res = requests.get(
"https://api.lucius.finance/v1/billing/contracts/acme-corp-2026/pricing",
headers={"Authorization": "Bearer luc_live_YOUR_KEY"},
)
print(res.json()["rules"])Response:
{
"object": "pricing_program",
"contract": "acme-corp-2026",
"version": 1,
"rules": [
{
"name": "Platform Subscription",
"type": "subscription",
"model": "flat",
"amount": "2000",
"frequency": "monthly"
},
{
"name": "Usage Fee",
"type": "usage",
"model": "percentage",
"rate": 0.05,
"metric": "revenue_amount_invoiced"
}
]
}The usage rule charges 5% of revenue_amount_invoiced.
Step 3: Submit usage
Submit a usage event. Each event needs a unique event_id for idempotency.
curl -X POST https://api.lucius.finance/v1/billing/usage \
-H "Authorization: Bearer luc_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"events": [{
"external_contract_id": "acme-corp-2026",
"event_id": "evt-2026-03-001",
"metric": "revenue_amount_invoiced",
"quantity": 10000,
"timestamp": "2026-03-25T12:00:00.000Z"
}]
}'const res = await fetch("https://api.lucius.finance/v1/billing/usage", {
method: "POST",
headers: {
Authorization: "Bearer luc_live_YOUR_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
events: [{
external_contract_id: "acme-corp-2026",
event_id: "evt-2026-03-001",
metric: "revenue_amount_invoiced",
quantity: 10000,
timestamp: "2026-03-25T12:00:00.000Z",
}],
}),
});
const result = await res.json();
console.log(result);res = requests.post(
"https://api.lucius.finance/v1/billing/usage",
headers={
"Authorization": "Bearer luc_live_YOUR_KEY",
"Content-Type": "application/json",
},
json={
"events": [{
"external_contract_id": "acme-corp-2026",
"event_id": "evt-2026-03-001",
"metric": "revenue_amount_invoiced",
"quantity": 10000,
"timestamp": "2026-03-25T12:00:00.000Z",
}]
},
)
print(res.json())Response:
{
"accepted": 1,
"rejected": 0,
"events": [{ "event_id": "evt-2026-03-001", "status": "accepted" }]
}The event was accepted, rated at 10,000 × 5% = $500.00, and the draft invoice was updated.
Step 4: Verify the event
Confirm the event was rated by looking it up.
curl https://api.lucius.finance/v1/billing/usage/evt-2026-03-001 \
-H "Authorization: Bearer luc_live_YOUR_KEY"const res = await fetch(
"https://api.lucius.finance/v1/billing/usage/evt-2026-03-001",
{ headers: { Authorization: "Bearer luc_live_YOUR_KEY" } },
);
console.log(await res.json());res = requests.get(
"https://api.lucius.finance/v1/billing/usage/evt-2026-03-001",
headers={"Authorization": "Bearer luc_live_YOUR_KEY"},
)
print(res.json())Response:
{
"object": "usage_event",
"id": "evt-2026-03-001",
"contract": "acme-corp-2026",
"metric": "revenue_amount_invoiced",
"quantity": 10000,
"status": "rated",
"ingested_at": "2026-03-05T11:21:59.868Z"
}Status is rated — the charge has been created.
Step 5: Check the invoice
Find the invoice that includes your usage charge.
curl "https://api.lucius.finance/v1/billing/invoices/INV-2026-003" \
-H "Authorization: Bearer luc_live_YOUR_KEY"const res = await fetch(
"https://api.lucius.finance/v1/billing/invoices/INV-2026-003",
{ headers: { Authorization: "Bearer luc_live_YOUR_KEY" } },
);
console.log(await res.json());res = requests.get(
"https://api.lucius.finance/v1/billing/invoices/INV-2026-003",
headers={"Authorization": "Bearer luc_live_YOUR_KEY"},
)
print(res.json())Response:
{
"object": "invoice",
"number": "INV-2026-003",
"status": "draft",
"total": 2500,
"currency": "USD",
"billing_period": { "start": "2026-03-01", "end": "2026-03-31" },
"line_items": [
{ "description": "Platform Subscription", "quantity": 1, "unit_price": 2000, "amount": 2000 },
{ "description": "Usage Fee", "quantity": 10000, "unit_price": 0.05, "amount": 500 }
]
}The usage charge of $500.00 appears alongside the $2,000 subscription charge, totalling $2,500.
What's next?
- Authentication — API key details and security
- Idempotency — Safe retries and duplicate handling
- Pagination — Paginate through large result sets
- API Reference — Full endpoint documentation