Billing Architecture and Usage Metering

Documentation Index

Fetch the complete documentation index at: https://docs.unprice.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

1. Core Concepts: Events vs. Meters vs. Features

​

Events

• They are append-only records of activity.
• They should describe what happened at the moment it happened.
• They are the input to usage metering.

• api.request_made
• ai.tokens_generated
• storage.snapshot_taken

​

Meters

• A meter is only relevant for usage entitlements.
• A meter decides how incoming events should be aggregated during the active billing cycle.
• The result is what Unprice uses for billing, limits, and reporting on usage-based features.

• “Count every API request this month”
• “Sum all bandwidth transferred this month”
• “Track the highest storage watermark reported this month”

​

Features

• A feature might be a metered capability, like API requests.
• A feature might also be simple access, like SSO or priority support.
• A feature can exist without any meter if it is not usage-based.

• pro-api-access
• database-storage
• priority-support

​

2. Supported Aggregation Methods

​

sum

• Best for values that accumulate naturally.
• Common examples are tokens, bytes, seconds, or credits consumed.
• The total resets at the end of the billing period.

​

count

• Best for request-style or action-style metrics.
• Common examples are API calls, export jobs, or webhook deliveries.
• The count resets at the end of the billing period.

​

max

• Best for high-watermark billing.
• Common examples are storage, peak concurrent users, or largest queue depth.
• The recorded maximum resets at the end of the billing period.

​

last

• Best for end-of-period state.
• Common examples are active seats, enabled workspaces, or the final storage total at billing time.
• The stored value resets with the next billing period after that period closes.

​

3. Handling “Stateful” Metrics (The “Fast Cache, Slow Truth” Pattern)

​

Streaming metrics

• API calls
• tokens generated
• emails sent
• files processed

const { result, error } = await unprice.customers.reportUsage({
  customerId: "cus_1234567890",
  featureSlug: "api-requests",
  usage: 1,
  idempotenceKey: request.id,
  metadata: {
    route: "/v1/chat/completions",
    method: "POST"
  }
});

if (error) {
  throw error;
}

if (!result?.allowed) {
  return new Response("Usage limit reached", { status: 429 });
}

​

Stateful metrics

• rows stored
• active users
• provisioned seats
• bytes stored

• retries can double-apply a change
• dropped network requests can lose a decrement
• race conditions can reorder updates
• backfills and imports can skip historical events
• deletes are often harder to observe reliably than creates

​

Real-time enforcement: Fast Cache

• Keep the hot path in systems you control, such as Redis or your primary application database.
• Decide whether to allow or block the request before doing expensive work.
• Treat this as the fast operational check, not the source of billing truth.

​

Accurate billing: Slow Truth

• Run hourly or daily, depending on how quickly the metric changes.
• Send the full current value, not a delta.
• Configure the meter as max if you bill on the highest watermark reached during the period.
• Configure the meter as last if you bill on the latest value at period close.

async function syncActiveSeats(customerId: string) {
  const row = await db.query<
    { active_seats: number }
  >(
    `
      SELECT COUNT(*)::int AS active_seats
      FROM seats
      WHERE customer_id = $1
        AND revoked_at IS NULL
    `,
    [customerId]
  );

  const activeSeats = row[0]?.active_seats ?? 0;

  await unprice.customers.reportUsage({
    customerId,
    featureSlug: "active-seats",
    usage: activeSeats,
    idempotenceKey: `active-seats:${customerId}:${new Date().toISOString().slice(0, 13)}`,
    metadata: {
      source: "cron",
      metricType: "snapshot"
    }
  });
}

SELECT SUM(bytes_used) AS total_bytes
FROM files
WHERE customer_id = $1;

​

4. How to Handle “Lifetime” Limits (e.g., Lifetime Free Trials)

• Create a normal usage feature for the activity you want to track.
• Use a standard usage meter for that feature.
• Configure the customer’s grant or entitlement so it does not expire and does not reset.
• Let the grant carry the long-lived allowance while the meter continues to process usage events normally.

• You want to give every free customer 10,000 API calls total.
• Keep the feature as api-requests.
• Meter the activity as normal usage.
• Create a non-expiring grant with a limit of 10,000.

• events still describe activity
• meters still aggregate usage
• entitlements and grants still define what the customer is allowed to consume

​

Best Practices

• Use meters only for usage entitlements.
• Use count or sum for streaming activity reported directly from the request path.
• Use scheduled snapshot events for stateful resources.
• Use max for high-watermark billing and last for end-of-period state billing.
• Enforce hard operational limits in your own app or cache layer first.
• Model long-lived allowances as grant or entitlement rules rather than inventing a separate metering model.

• Read Entitlements to understand how features become customer access rules.
• Read Report Usage for the SDK contract and request shape.