Customers

A customer in Brilo represents a billing entity — typically one of your end users or accounts. All subscriptions, invoices, and credits belong to a customer.

The Customer Object

{
  "customer_id": "cust_123",
  "customer_name": "Acme Corp",
  "email": "[email protected]",
  "default_currency": {
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$"
  },
  "payment_provider": "stripe",
  "payment_provider_id": "cus_stripe_abc123",
  "has_payment_method": true,
  "tax_rate": 10.5,
  "timezone": "America/New_York",
  "billing_address": {
    "line1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "subscriptions": [...],
  "invoices": [...],
  "total_amount_due": 99.00
}

Key Fields

Field	Type	Description
`customer_id`	string	Your internal identifier for this customer — set by you at creation
`customer_name`	string	Display name
`email`	string	Primary billing email
`default_currency`	object	The currency used for this customer's invoices
`has_payment_method`	boolean	Whether a valid payment method is on file
`tax_rate`	number	Tax rate as a percentage, e.g. `10.5` for 10.5%
`timezone`	string	IANA timezone string, used for billing period calculations
`billing_address`	object	Address used on invoices
`total_amount_due`	number	Sum of all unpaid invoice balances

Customer IDs

customer_id is set by you when creating the customer. Brilo does not generate its own customer IDs.

Use your existing internal customer or account ID. This makes it trivial to look up a Brilo customer from your database without maintaining a separate ID mapping.

// Good — matches your internal user/account ID
{ "customer_id": "user_8821", ... }
{ "customer_id": "org_acme", ... }
{ "customer_id": "acct-00123", ... }

// Avoid — opaque IDs that don't map to anything in your system
{ "customer_id": "a84f2c91-...", ... }

Customer IDs must be unique within your Brilo account. Attempting to create a customer with a duplicate ID returns 409 Conflict.

Creating a Customer

curl -X POST https://api.brilo.tech/api/customers/ \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "customer_name": "Acme Corp",
    "email": "[email protected]",
    "default_currency_code": "USD",
    "timezone": "America/New_York",
    "tax_rate": 10.5
  }'

Required fields: customer_id, email

See Create a customer.

Retrieving Customers

Get a single customer

curl "https://api.brilo.tech/api/customers/cust_123/" \
  -H "X-API-KEY: your-api-key"

The response includes the customer's current subscriptions, recent invoices, and total amount due. See Retrieve a customer.

List all customers

curl "https://api.brilo.tech/api/customers/" \
  -H "X-API-KEY: your-api-key"

Results are paginated. See List customers.

Draft Invoices

To see what a customer currently owes before their billing period ends, use the draft invoice endpoint:

curl "https://api.brilo.tech/api/customers/cust_123/draft_invoice/" \
  -H "X-API-KEY: your-api-key"

This returns a projected invoice based on usage so far in the current period. It is not finalized and may change before the billing period ends. See List Draft Invoices.

Customer Profitability

Brilo tracks daily revenue, cost, and margin per customer. Use this to understand which customers are most profitable:

curl "https://api.brilo.tech/api/customers/cust_123/cost_analysis/" \
  -H "X-API-KEY: your-api-key"

See Get Customer Profitability.

Deleting a Customer

curl -X POST https://api.brilo.tech/api/customers/cust_123/delete/ \
  -H "X-API-KEY: your-api-key"

See Delete a customer.

Next Steps

refresh

Subscriptions

Subscribe customers to plans

file-text

Invoices

View and manage customer invoices

credit-card

Credits & Refunds

Issue credits to customers