---
title: "Membership & Credits"
description: "Ring membership tiers and credit balance — the six-role ladder, RING-token upgrade pricing with desk oracle, PaymentConductor checkout rails, and the subscription ledger"
locale: "en"
---
# Membership & Credits

> **Info**
> Use **Founder** / **Developer** tabs in the docs sidebar to filter this page. Member-facing flows render at `/membership`; this article documents the tiers, pricing, and payment rails.

Membership is how a Ring clone distinguishes community tiers and monetizes access. The role ladder is the SSOT (`features/auth/user-role.ts`), upgrade pricing is config-driven (`lib/membership/pricing.ts`), and every payment — card, credit balance, PayPal, or native token — flows through PaymentConductor.

## Role ladder (SSOT)

| Role | Meaning |
|------|---------|
| `visitor` | Non-authenticated, viewing-only |
| `subscriber` | Paying basic subscriber — baseline community access |
| `member` | Elevated status with more access |
| `confidential` | Access to confidential resources |
| `admin` | Platform admin |
| `superadmin` | Top-level platform admin |

Upgrades move a user from `subscriber` → `member`. `confidential` tier config explicitly requires the confidential role.

### For founders

## Why this matters for your clone

- **Monetize access** with a paid member tier while visitors and subscribers keep baseline access.
- **One checkout, many rails.** PaymentConductor unifies card, credit balance, PayPal, and native token — the same checkout engine as the store.
- **Predictable RING pricing.** Monthly upgrade defaults to **1 RING** (`membership.ring.memberUpgradeAmount`), yearly gets **20% off** monthly × 12, and live quotes use the desk oracle so the billed amount matches the quote.
- **Credit balance is the core denomination.** Above 10 credit units (`MEMBERSHIP_DESK_CREDIT_HINT_MIN`), the UI hints the Token Desk swap instead of buying credit.

### Operator checklist

1. Confirm your payment processors in PaymentConductor (WayForPay / Stripe / PayPal per clone).
2. Review `membership.ring` amounts and the `member` tier config in `ring-config.json`.
3. Run one real upgrade per rail (card, credit, token) in a staging clone before go-live.

### For developers

## Pricing modules (verified)

| Module | Role |
|--------|------|
| `lib/membership/pricing.ts` | Sync helpers — RING amounts per period, annual 20% discount, credit desk hint |
| `lib/membership/pricing-live.ts` | Server-only live desk quotes via `getNativeTokenToMainCurrencyRate` |
| `lib/payments/conductor/handlers/membership-upgrade.ts` | Upgrade purpose handling |
| `lib/payments/conductor/handlers/membership-upgrade-stripe.ts` / `-paypal.ts` | Provider-specific upgrade rails |
| `lib/payments/payment.config.ts` | `membership_upgrade` purpose → `PAYMENT_MEMBERSHIP_PROCESSOR` |

## API surface

| Route | Methods | Purpose |
|-------|---------|---------|
| `/api/membership/payment/card` | POST, GET | Card checkout for membership |
| `/api/membership/payment/credit` | POST, GET | Credit-balance payment path |
| `/api/membership/payment/paypal` | POST, GET | PayPal checkout |
| `/api/membership/payment/token` | POST, GET | Native token payment |
| `/api/membership/subscription/create` | POST | Create a subscription |
| `/api/membership/subscription/status` | GET | Read subscription status |
| `/api/membership/subscription/cancel` | POST, GET | Cancel a subscription |

## Ledger truth

**Where money lands**

Paid upgrades write to the **subscription ledger** (`subscription_ledger`) — the `credit_balance` provider marks credit-paid renewals (`next_payment_due` indexed in `data/schema.sql`). Credit itself lives on the user record (`users.data.credit_balance`), with wallet transactions as the audit trail (`features/wallet/services/credit-balance-service.ts`).

**Billing periods**

`MembershipBillingPeriod = 'monthly' | 'yearly'`. Yearly cost = `annualUpgradeAmount` when set, otherwise monthly × 12 × 0.8 (20% off). Tier shape: `MemberTierConfig { amount, currency, description, duration }`.

## Related documentation

  
- [features/wallet-conductor](/docs/features/wallet-conductor.md) — Deep-dive: the credit ledger and two-rate SSOT membership payments settle into.

  
- [features/payment-conductor](/docs/features/payment-conductor.md) — Depends-on: card, PayPal, and token rails all run through PaymentConductor.

  
- [features/subscriptions](/docs/features/subscriptions.md) — Same-workflow: renewal lifecycle and cancellation handling.

  
- [architecture/data-model](/docs/architecture/data-model.md) — See-also: how credit_balance and the subscription ledger live in the JSONB schema.