Customers
Create customers via the API and store your own id as `external_id`.
POST /v1/billing/customers creates a customer and fires customer.created. The only required field is name.
curl -X POST https://api.lucius.finance/v1/billing/customers \
-H "Authorization: Bearer luc_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Corp",
"email": "billing@acme.com",
"external_id": "cust_acme"
}'{
"object": "customer",
"id": "316301ff-ecd8-48cc-a4c4-92c7c6ba33f1",
"external_id": "cust_acme",
"name": "Acme Corp",
"email": "billing@acme.com",
"domain": null,
"country": null,
"created_at": "2026-10-02T10:00:00.000Z"
}id is the Lucius UUID. Use it as customer_id when creating a contract. external_id is yours.
Fields
| Field | Required | Notes |
|---|---|---|
name | Yes | Display name |
external_id | No | Your id. Unique per company. Duplicate → 409 with the existing customer |
email | No | |
domain | No | |
country | No | |
address | No | |
registration_number | No | Legal entity number (Companies House, EIN). Not a join key |
payment_terms_days | No | Stored as Net {n} |
We do not match or upsert by name. Send external_id if you need to join later.
Lookup
curl "https://api.lucius.finance/v1/billing/customers?external_id=cust_acme" \
-H "Authorization: Bearer luc_live_YOUR_KEY"Scopes
customers:write or usage:write to create. customers:read or usage:write to list.
See Create a customer and List customers.