SPEC 011: Billing and Subscriptions

Status: DRAFT Priority: P0 Created: 2026-02-21 Approved: pending Repo(s): equa-web, equa-server

1. Feature Purpose

The Billing and Subscriptions module handles the commercial side of the Equa platform: subscription tier management, payment profile collection, checkout flows, coupon redemption, and waitlist positioning. It integrates with Chargify as the external payment processor and subscription lifecycle manager. The module enforces tier-based limits (e.g. member caps) across the platform and provides self-service upgrade/downgrade flows for organization admins.

2. Current State (Verified)

Frontend modules:

equa-web/src/modules/payments/
├── components/   # Billing dashboard, payment profiles, checkout
├── services/     # API client for billing operations
├── store/        # Payment and subscription state
└── index.tsx

equa-web/src/modules/subscriptions/
├── components/   # Subscription management, plan selection, upgrade/downgrade
├── services/     # API client for subscription operations
├── store/        # Subscription state
└── index.tsx

Frontend service layer:

equa-web/src/service/services/payments   # Shared payment service utilities

Backend module:

equa-server/modules/billing/
├── src/
│   ├── chargify/      # Chargify API client and webhook handlers
│   ├── services/      # Billing business logic
│   └── entity/        # Billing-related entities

Backend endpoints:

equa-server/modules/api/src/endpoints/billing-endpoints.ts

3. Data Model

Entities

Entity	Description	File
MemberLimits	Enforces subscription-tier member caps per organization	`equa-server/modules/persistence/src/entity/MemberLimits.ts`
UserCoupons	Coupon codes redeemed by users	`equa-server/modules/persistence/src/entity/UserCoupons.ts`
Waitlists	Pre-launch or tier-gated waitlist positions	`equa-server/modules/persistence/src/entity/Waitlists.ts`

Key Fields — MemberLimits

Field	Type	Nullable	Description
`organization`	`uuid`	No	Organization this limit applies to
`memberLimit`	`integer`	No	Maximum team members allowed by current subscription tier

Key Fields — UserCoupons

Field	Type	Nullable	Description
`user`	`uuid`	No	User who redeemed the coupon
`code`	`string`	No	Coupon code

Key Fields — Waitlists

Field	Type	Nullable	Description
`id`	`uuid`	No	Primary key
`user`	`uuid`	No	User on the waitlist
`position`	`integer`	No	Queue position

Relationships

External Integration: Chargify

Chargify manages the canonical subscription state. The Equa backend syncs via:

API calls to Chargify for creating/updating subscriptions, applying coupons, and managing payment profiles.
Webhooks from Chargify for subscription lifecycle events (activation, renewal, cancellation, payment failure, dunning).

The local MemberLimits entity is updated when subscription tier changes are confirmed by Chargify.

4. API Endpoints

Served by equa-server/modules/api/src/endpoints/billing-endpoints.ts.

Method	Path	Auth	Description
GET	`/v1/billing/subscriptions`	Session	Get current user’s subscriptions
POST	`/v1/billing/subscriptions`	Session	Create a new subscription (triggers Chargify)
PUT	`/v1/billing/subscriptions/:id`	Session	Update subscription (upgrade/downgrade)
DELETE	`/v1/billing/subscriptions/:id`	Session	Cancel a subscription
GET	`/v1/billing/payment-profiles`	Session	List payment profiles on file
POST	`/v1/billing/payment-profiles`	Session	Add a payment profile
PUT	`/v1/billing/payment-profiles/:id`	Session	Update a payment profile
DELETE	`/v1/billing/payment-profiles/:id`	Session	Remove a payment profile
POST	`/v1/billing/coupons/redeem`	Session	Redeem a coupon code
GET	`/v1/billing/coupons/validate/:code`	Session	Validate a coupon code without redeeming
GET	`/v1/billing/plans`	Public	List available subscription plans and pricing
POST	`/v1/billing/checkout`	Session	Initiate checkout flow
GET	`/v1/billing/invoices`	Session	List billing invoices
POST	`/v1/billing/webhooks/chargify`	Webhook	Chargify webhook receiver
GET	`/v1/waitlist/status`	Session	Get user’s waitlist position
POST	`/v1/waitlist/join`	Session	Join the waitlist

5. Frontend Components

Payments Module

Component	File	Purpose
BillingDashboard	`equa-web/src/modules/payments/components/BillingDashboard.tsx`	Overview of billing status, invoices, payment method
PaymentProfileForm	`equa-web/src/modules/payments/components/PaymentProfileForm.tsx`	Add/edit credit card or bank account
CheckoutFlow	`equa-web/src/modules/payments/components/CheckoutFlow.tsx`	Multi-step checkout with plan selection and payment
InvoiceList	`equa-web/src/modules/payments/components/InvoiceList.tsx`	View past invoices
CouponInput	`equa-web/src/modules/payments/components/CouponInput.tsx`	Coupon code entry and validation

Subscriptions Module

Component	File	Purpose
SubscriptionManager	`equa-web/src/modules/subscriptions/components/SubscriptionManager.tsx`	Current plan details, upgrade/downgrade
PlanSelector	`equa-web/src/modules/subscriptions/components/PlanSelector.tsx`	Compare and select subscription tiers
UsageMeter	`equa-web/src/modules/subscriptions/components/UsageMeter.tsx`	Show usage vs. tier limits (e.g. members)

Routes

Route	Component	Description
`/settings/billing`	BillingDashboard	Billing overview and payment methods
`/settings/billing/checkout`	CheckoutFlow	New subscription checkout
`/settings/subscription`	SubscriptionManager	Current subscription management
`/pricing`	PlanSelector	Public pricing / plan comparison

State Management

Payment and subscription state is split across two module stores. The payments store manages payment profiles, invoices, and checkout state. The subscriptions store manages the active subscription, tier details, and usage. Both sync with Chargify-backed API endpoints.

6. Business Rules and Validation

Rule	Description	Enforcement
BIL-001	An organization cannot add members beyond its `MemberLimits.memberLimit`	Backend
BIL-002	A coupon code can only be redeemed once per user	Backend
BIL-003	Subscription downgrades take effect at the end of the current billing period	Backend (Chargify)
BIL-004	Subscription upgrades take effect immediately with prorated billing	Backend (Chargify)
BIL-005	A valid payment profile is required before creating a subscription	Both
BIL-006	Webhook payloads from Chargify must be signature-verified before processing	Backend
BIL-007	Failed payments trigger dunning workflow managed by Chargify; after final failure, subscription is suspended	Backend (Chargify)
BIL-008	Waitlist position is immutable once assigned; users cannot change their position	Backend
BIL-009	Cancelled subscriptions retain read-only access until the end of the paid period	Backend

7. Acceptance Criteria

8. Risks and Edge Cases

Risk	Likelihood	Impact	Mitigation
Chargify API downtime blocks subscription changes	Low	High	Queue failed requests for retry; show user-friendly error with retry option
Webhook delivery failure causes state drift	Med	High	Periodic reconciliation job syncs Chargify state; idempotent webhook handler
Race condition: member added while downgrade pending	Low	Med	Check limit at member-add time against current (not pending) tier
Coupon abuse via code sharing	Med	Low	Rate-limit redemptions; tie coupons to specific campaigns
Payment profile PCI compliance	Low	Critical	Chargify handles card storage; Equa never stores raw card numbers
Waitlist position disputes	Low	Low	Position assigned server-side via auto-increment; no manual override

9. Dependencies

Dependency	Type	Status
SPEC 001: Authentication	Required before	DRAFT
SPEC 002: Organization Management	Required before	DRAFT
SPEC 012: Team Members and Roles	Integrates with	DRAFT
Chargify (external)	External integration	Active

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

SPEC 011: Billing and Subscriptions

SPEC 011: Billing and Subscriptions

1. Feature Purpose

2. Current State (Verified)

3. Data Model

Entities

Key Fields — MemberLimits

Key Fields — UserCoupons

Key Fields — Waitlists

Relationships

External Integration: Chargify

4. API Endpoints

5. Frontend Components

Payments Module

Subscriptions Module

Routes

State Management

6. Business Rules and Validation

7. Acceptance Criteria

8. Risks and Edge Cases

9. Dependencies

​SPEC 011: Billing and Subscriptions

​1. Feature Purpose

​2. Current State (Verified)

​3. Data Model

​Entities

​Key Fields — MemberLimits

​Key Fields — UserCoupons

​Key Fields — Waitlists

​Relationships

​External Integration: Chargify

​4. API Endpoints

​5. Frontend Components

​Payments Module

​Subscriptions Module

​Routes

​State Management

​6. Business Rules and Validation

​7. Acceptance Criteria

​8. Risks and Edge Cases

​9. Dependencies

SPEC 011: Billing and Subscriptions

1. Feature Purpose

2. Current State (Verified)

3. Data Model

Entities

Key Fields — MemberLimits

Key Fields — UserCoupons

Key Fields — Waitlists

Relationships

External Integration: Chargify

4. API Endpoints

5. Frontend Components

Payments Module

Subscriptions Module

Routes

State Management

6. Business Rules and Validation

7. Acceptance Criteria

8. Risks and Edge Cases

9. Dependencies