Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Track metered usage from your server for reliable billing.
await billing.trackUsage({
customerId: "user_123",
featureKey: "api_calls",
quantity: 1,
});
| Name | Type | Required | Description |
|---|---|---|---|
customerId | string | Yes | Customer external user ID |
featureKey | string | Yes | Which feature was used |
quantity | number | Yes | How many units to track (must be > 0) |
idempotencyKey | string | No | Prevent duplicate tracking on retries |
metadata | Record<string, any> | No | Additional context |
interface TrackUsageResponse {
success: boolean
feature_key: string
quantity: number
recorded_at: string
usage?: {
consumed_units: number
limit_units: number
remaining_units: number
period_start: string
period_end: string
}
}
idempotencyKey to prevent duplicate events (e.g., from retries):
await billing.trackUsage({
customerId: "user_123",
featureKey: "api_calls",
quantity: 1,
idempotencyKey: `api-call-${requestId}`,
});
const metrics = await billing.getUsageMetrics("user_123", "api_calls");
| Name | Type | Required | Description |
|---|---|---|---|
customerId | string | Yes | Customer external user ID |
featureKey | string | No | Filter to a specific feature |
interface UsageMetricsResponse {
metrics: UsageMetric[]
customer_id: string
}
interface UsageMetric {
feature_key: string
feature_title: string
product_name: string
consumed: number
limit: number
remaining: number
percentage_used: number
period_start: string
period_end: string
resets_in_days: number
}
export async function POST(request: Request) {
const userId = getAuthenticatedUser(request);
// Check if user has remaining quota
const entitlement = await billing.checkEntitlement(userId, "api_calls");
if (!entitlement.has_access) {
return Response.json({ error: "Plan upgrade required" }, { status: 403 });
}
if (entitlement.usage !== null && entitlement.limit !== null && entitlement.usage >= entitlement.limit) {
return Response.json({ error: "API call limit reached" }, { status: 429 });
}
// Do the work
const result = await processApiCall(request);
// Track the usage
await billing.trackUsage({
customerId: userId,
featureKey: "api_calls",
quantity: 1,
});
return Response.json(result);
}