Quickstart

This guide walks you through the core Brilo workflow end-to-end — from tracking your first event to generating a customer's invoice. By the end, you'll have a working billing setup.

Step 1: Track Usage Events

Every Brilo billing setup starts with events. Events are usage signals you send from your backend whenever a customer does something billable.

Send events to the Track an Event endpoint:

curl -X POST https://api.brilo.app/track \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "api_call_made",
    "customer_id": "customer_123",
    "idempotency_id": "evt_abc123",
    "time_created": "2024-05-01T10:00:00Z",
    "properties": {
      "endpoint": "/v1/messages",
      "tokens_used": 1200
    }
  }'

Key fields:

You can track as many event types as you want. Events are stored and only billed when referenced by a metric.

Step 2: Create a Metric

Metrics turn raw events into billable quantities. Navigate to Metrics → Create Metric in the dashboard, or define them via the API.

For example, to count the number of API calls:

• Metric name: api_calls
• Aggregation type: count
• Event filter: event_name = "api_call_made"

To bill by tokens used (a sum):

• Metric name: tokens_used
• Aggregation type: sum
• Property: tokens_used
• Event filter: event_name = "api_call_made"

Common aggregation types:

Step 3: Create a Pricing Plan

Plans define what to charge. Go to Plans → Create Plan in the dashboard.

A simple plan might look like:

• Name: Starter
• Recurring fee: $29/month
• Billing period: Monthly
• Component: api_calls — first 10,000 free, then $0.001 per call

For a usage-only plan with no base fee, set the recurring fee to $0 and add your components.

See Pricing & Plans for a full breakdown of pricing models.

Step 4: Create a Customer and Subscribe Them

Create a Customer

curl -X POST https://api.brilo.app/customers \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "customer_123",
    "email": "[email protected]",
    "name": "Acme Corp"
  }'

Use the same customer_id you're already using in your application — Brilo doesn't generate its own.

Subscribe Them to a Plan

curl -X POST https://api.brilo.app/subscriptions \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "customer_123",
    "plan_id": "plan_starter",
    "start_date": "2024-05-01",
    "auto_renew": true
  }'

From this point on, Brilo tracks the customer's usage against this plan and will generate an invoice at the end of their billing period.

Step 5: Connect a Payment Processor

When an invoice is ready, Brilo needs somewhere to send it. Go to Settings → Integrations and connect Stripe or Braintree via OAuth.

Once connected:

• Invoices are automatically pushed to Stripe/Braintree on their due date
• Payment collection and receipts are handled there
• Failed payments trigger a subscription.failed webhook event

No payment processor yet? You can also subscribe to the invoice.created webhook and handle payment collection yourself. See Webhooks for setup.

Verify Everything is Working

Use the Verify Events Received endpoint to confirm your events are being received:

curl -X POST https://api.brilo.app/verify-events \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_ids": ["evt_abc123", "evt_def456"],
    "lookback_days": 7
  }'

And check feature/metric access at any time to make sure entitlements are enforced correctly:

curl "https://api.brilo.app/metric-access?customer_id=customer_123&metric_id=api_calls" \
  -H "X-API-KEY: your-api-key"

What's Next