Usage Metering & Billing Engine

I built an Express API with Zod validation at the request boundary and a layered route, middleware, service, repository, and PostgreSQL design. The metering service checks for an existing event by tenant and idempotency key; a database uniqueness constraint and conflict recovery make concurrent retries of the same key resolve to the stored event. Quota enforcement checks subscription standing before the plan limit, returning 402 for a subscription that is not in good standing and 429 when the request would exceed its monthly allowance. Costs are calculated in integer micro-cents, with period totals summed before conversion to cents; the usage endpoint returns the resulting cost totals. Customers can pay for the fixed-price Pro subscription through Stripe-hosted Checkout ($29/month in the documented test setup). Stripe processes the subscription payment; signed, deduplicated webhooks report checkout and subscription events so the service can synchronize subscription status and the tenant's plan. The measured usage cost is reported by the API but is not separately charged through Stripe. A scheduled job checks usage-alert thresholds and records its runs, retrying failures up to three attempts with backoff. The scope deliberately uses a trusted x-tenant-id header rather than real authentication and UTC calendar months rather than Stripe billing periods. Quota checks and event insertion are separate operations, so concurrent requests with different keys can still overshoot a quota.