What is a Customer?
A customer represents a billing entity in your system. Events, limits, and balances are all scoped to customers.
| Field | Description | Example |
|---|
external_id | Your ID for the customer | "cust_123", "org_acme" |
name | Display name | "Acme Corp" |
email | Contact email for alerts | "billing@acme.com" |
billing_cycle_start | When billing periods begin | "2024-01-15" |
timezone | Timezone for period calculations | "America/New_York" |
metadata | Custom data for integrations | {"stripe_id": "cus_xxx"} |
Creating Customers
customer = client.customers.create(
external_id="cust_123",
name="Acme Corp",
email="billing@acme.com"
)
Auto-Creation from Events
Customers are automatically created when you record events with a new customer_id:
# This creates customer "new_cust" if it doesn't exist
client.events.record(
customer_id="new_cust",
event_type="llm.completion",
values={"tokens": 500}
)
Billing Cycles
Custom Billing Start Date
Set when a customer’s billing period begins:
customer = client.customers.create(
external_id="cust_123",
name="Acme Corp",
billing_cycle_start="2024-03-15" # Bills on the 15th
)
month and annual limits are calculated:
| Billing Cycle Start | Monthly Period |
|---|
| Jan 1 | Jan 1 - Jan 31 |
| Jan 15 | Jan 15 - Feb 14 |
| Mar 1 | Mar 1 - Mar 31 |
Timezone
Set the customer’s timezone for accurate period boundaries:
customer = client.customers.create(
external_id="cust_123",
name="Acme Corp",
timezone="America/New_York"
)
If not specified, timezone falls back to the project default, then UTC.
customer = client.customers.create(
external_id="cust_123",
name="Acme Corp",
metadata={
"stripe_customer_id": "cus_xxx",
"stripe_subscription_id": "sub_xxx",
"plan": "pro",
"tier": "enterprise"
}
)
- Link to Stripe/Chargebee customer IDs
- Store plan or tier information
- Track custom attributes
Retrieving Customers
# Get by external ID
customer = client.customers.retrieve("cust_123")
print(f"Name: {customer.name}")
print(f"Billing cycle: {customer.billing_cycle_start}")
print(f"Metadata: {customer.metadata}")
Updating Customers
customer = client.customers.update(
"cust_123",
name="Acme Corporation",
metadata={
"plan": "enterprise",
"stripe_customer_id": "cus_xxx"
}
)
Listing Customers
customers = client.customers.list()
for customer in customers.data:
print(f"{customer.external_id}: {customer.name}")
# Pagination
if customers.has_more:
next_page = client.customers.list(cursor=customers.next_cursor)
Deleting Customers
client.customers.delete("cust_123")
Deleting a customer also deletes their associated limits and balances. Events are retained for historical records.
Customer Usage
Get a customer’s usage data:
# Get usage summary for a customer
usage = client.customers.usage("cust_123")
print(f"Total events: {usage.total_events}")
print(f"Values: {usage.values}")
# Get customer's balances
balances = client.customers.balances("cust_123")
for balance in balances.data:
print(f"{balance.name}: {balance.current_balance} {balance.unit}")
Integrating with Stripe
A common pattern for syncing with Stripe:
import stripe
# When a Stripe subscription is created
def handle_subscription_created(subscription):
customer = client.customers.create(
external_id=subscription.customer,
metadata={
"stripe_customer_id": subscription.customer,
"stripe_subscription_id": subscription.id,
"plan": subscription.items.data[0].price.lookup_key
},
billing_cycle_start=subscription.current_period_start
)
# Create limits based on plan
if subscription.items.data[0].price.lookup_key == "pro":
client.limits.create(
meter_id="mtr_tokens",
limit_value=1000000,
period="month",
customer_id=subscription.customer
)
