Billing & Payments Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Billing & Payments Integration in Barekey manages the monetization and usage-based tracking for organization workspaces. It defines the relationship between service tiers, usage limits (such as static/dynamic requests and storage), and the billing intervals applied to organizations. The system is designed to scale from individual developers to high-growth teams through three distinct plan tiers: Free, Pro, and Max.
While the user interface provides a comprehensive breakdown of these tiers and overage costs, the backend implementation is currently architected as a scaffold. The project identifies "Autumn" as the intended payment provider for future integration, with backend logic intended to reside within the pkg/convex/payments/ directory.
Sources: AGENTS.md:21, pkg/ui/src/pages/o/[org]/billing/page.tsx:24-81
Plan Tiers and Pricing Structure
Barekey categorizes service levels into three tiers. Each tier offers different levels of static requests, dynamic requests, and storage capacity.
Service Tiers Summary
| Plan | Purpose | Monthly Price (USD) | Support Level | Features |
|---|---|---|---|---|
| Free | Personal projects | $0 | Community | Limited to 1 org/user |
| Pro | Growing teams | $9 | Includes overage options | |
| Max | Production workloads | $39 | Priority | Audit exports & advanced logs |
Sources: pkg/ui/src/pages/o/[org]/billing/page.tsx:25-78
Billing Configurations
The integration supports two primary configuration toggles for organization billing:
- Billing Interval: Users can choose between "Monthly" or "Annually". Annual billing provides a 20% discount on the base monthly price.
- Overage Mode: Organizations can be configured "With overages" or "Without overages". When overages are enabled, usage beyond the tier limits is billed monthly regardless of the base billing interval.
Sources: pkg/ui/src/pages/o/[org]/billing/page.tsx:106-121, pkg/ui/src/pages/o/[org]/billing/page.tsx:245-247
Usage Limits and Overage Logic
Usage is tracked across three primary metrics. If a plan supports overages, specific rates are applied per 1,000 requests once the base limit is exceeded.
Metric Definitions and Overage Rates
| Metric | Free Limit | Pro Limit | Max Limit | Overage Rate (Pro) | Overage Rate (Max) |
|---|---|---|---|---|---|
| Static Requests | 10k | 250k | 2M | $1.50 per 250k | $1.00 per 250k |
| Dynamic Requests | 500 | 5k | 25k | $4.00 per 5k | $2.50 per 5k |
| Storage | 25 MB | 250 MB | 2 GB | N/A | N/A |
Sources: pkg/ui/src/pages/o/[org]/billing/page.tsx:25-78
UI Integration and Logic Flow
The following diagram illustrates how the billing UI determines the displayed price and overage information based on user selection.
The UI utilizes formatting helpers like formatUsd and formatUsdPerThousand to ensure technical precision in pricing displays.
Sources: pkg/ui/src/pages/o/[org]/billing/page.tsx:86-101, pkg/ui/src/pages/o/[org]/billing/page.tsx:156-174
Architecture and Future Implementation
The billing system is currently in a transitional state from UI scaffolding to backend enforcement.
Integration Components
- Autumn Integration: Identified as the future payment processor. The directory
pkg/convex/payments/is reserved for this logic but currently remains empty. - Convex Backend: The backend hosts the "active org" logic. While the UI displays usage metrics (Static, Dynamic, Storage), the
OrgMetricCardcomponents on the overview page indicate that "Usage limits tracking" is pending implementation. - Organization Context: Billing is scoped to the organization level. Every user receives a default organization, but the Free plan is restricted to one organization per user.
Sources: AGENTS.md:21, AGENTS.md:46, pkg/ui/src/pages/o/[org]/overview/page.tsx:61-79, pkg/ui/src/pages/o/[org]/billing/page.tsx:238-242
System Relationships
The following entity relationship diagram shows how billing concepts relate to the core data model.
Projects and secrets (variables) are currently "unlimited" across all tiers as part of the "Always included" features, though the organization ownership limits the scope of these assets based on the active plan.
Sources: pkg/ui/src/pages/o/[org]/billing/page.tsx:82-87, pkg/convex/projects.ts:108-118, AGENTS.md:55
Conclusion
The Billing & Payments Integration provides a structured tier system designed for scalability. While the frontend offers a high-fidelity preview of the billing experience—including tiered pricing, annual discounts, and overage calculations—the backend infrastructure is prepared for a future integration with the Autumn payment platform. Significant features such as audit exports and priority support are gated behind higher-tier plans, while core features like unlimited projects and variables remain standard across all levels.