StripeMeter

StripeMeter is a Stripe-native usage metering system that ensures correct usage totals for usage-based billing. It dedupes retries, handles late events with watermarks, keeps running counters, and pushes only deltas to Stripe.

Quick Start

git clone https://github.com/geminimir/stripemeter && cd stripemeter
cp .env.example .env && docker compose up -d && pnpm -r build
pnpm db:migrate && pnpm dev

Core Concepts

Events (Immutable Ledger)

Every usage event stored with deterministic idempotency key. Events are never deleted or modified.

Counters (Materialized Aggregations)

Pre-computed aggregations (sum/max/last) by tenant, metric, customer, and period. Updated in near-real-time.

Watermarks (Late Event Handling)

Each counter maintains a watermark timestamp. Events within lateness window (default 48h) trigger re-aggregation.

Delta Push (Stripe Synchronization)

Tracks pushed_total per subscription item and only sends delta to Stripe.

API Endpoints

Ingest Events

curl -X POST http://localhost:3000/v1/events/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "tenantId": "your-tenant-id",
      "metric": "api_calls",
      "customerRef": "cus_ABC123",
      "quantity": 100,
      "ts": "2025-01-16T14:30:00Z"
    }]
  }'

Get Cost Projection

curl -X POST http://localhost:3000/v1/usage/projection \
  -H "Content-Type: application/json" \
  -d '{"tenantId": "your-tenant-id", "customerRef": "cus_ABC123"}'

Health & Metrics

• Readiness: GET /health/ready
• Metrics: GET /metrics
• Events: GET /v1/events?tenantId=X&limit=10

Node.js SDK

import { createClient } from '@stripemeter/sdk-node';

const client = createClient({
  apiUrl: 'http://localhost:3000',
  tenantId: 'your-tenant-id',
  customerId: 'cus_ABC123'
});

// Track usage
await client.track({
  metric: 'api_calls',
  customerRef: 'cus_ABC123',
  quantity: 100,
  meta: { endpoint: '/v1/search' }
});

// Get live usage
const usage = await client.getUsage('cus_ABC123');
const projection = await client.getProjection('cus_ABC123');

Python SDK

from stripemeter import StripeMeterClient

client = StripeMeterClient(
    api_url="http://localhost:3000",
    tenant_id="your-tenant-id",
    customer_id="cus_ABC123"
)

client.track(
    metric="api_calls",
    customer_ref="cus_ABC123",
    quantity=100
)

Stripe Billing Driver

For direct Stripe integration, use the stripe-driver package:

import { StripeBillingDriverImpl } from '@stripemeter/stripe-driver';

const driver = new StripeBillingDriverImpl({
  liveKey: process.env.STRIPE_SECRET_KEY,
  testKey: process.env.STRIPE_TEST_SECRET_KEY
});

// Record usage to Stripe
await driver.recordUsage({
  mode: 'live',
  stripeAccount: 'default',
  subscriptionItemId: 'si_xxx',
  quantity: 100,
  periodStart: '2025-01-01',
  idempotencyKey: 'unique-key'
});