Memberships

A membership tier is the offer a buyer accepts to join a community — Free, Pro, Founding Member, "3× installment", whatever you call it. One community can have many tiers, and one buyer can hold one tier at a time per community.

This page is the reference for how a tier is configured, what prices it can carry, how those prices interact, what the buyer sees at apply time, how renewals and cancellations play out, and what webhooks fire so you can integrate from your own system.

Mental model. A tier is a bundle of three things:

1. An offer — one or more prices, each tied to a billing cycle.
2. An application form (optional, configurable per tier).
3. A commitment shape — recurring, one-time, fixed-N installments, or installments that auto-renew yearly.

Everything below describes the surface area for configuring (1) and (3). For (2), see the Segments REST API.

1. The configuration surface

A tier exposes five nullable price fields and one boolean modifier:

Plus the installment-specific config (all-or-nothing):

All seven fields are independent. Any combination is valid provided the installment fields are all-set-or-all-null.

2. The six buyer experiences

The fields above compose into six distinct buyer experiences. The picker on the apply page renders one row per experience the tier offers; if only one is configured, no picker is shown.

The buyer sees the same cycle name INSTALLMENT_PLAN regardless of whether it renews; the renewal modifier is set on the segment, not on the buyer's choice.

3. Mixing payment styles on a single tier

This is the headline feature: one tier can offer multiple ways to pay and the buyer picks at apply time.

Example: tier with "Pay once a year" + "3× monthly"

Configured with:

priceYearly:               33000   (€330/yr)
installmentTotalPrice:     33000   (€330 total)
installmentCount:          3       (3 charges)
installmentIntervalMonths: 1       (monthly)
accessDurationMonths:      12      (1 year access window)
installmentRenewsAnnually: true    (3× cycle repeats annually)

A buyer arriving at the apply page sees a picker with two options:

1. Pay every year — €330/year. Auto-renews until cancelled.
2. Pay €330/year in 3× — €110 every month. 3 payments per year, auto-renews until cancelled.

Both result in the same €330/year revenue commitment for the community; the buyer chooses the cash-flow shape that fits them.

Example: "Pro tier" with monthly + yearly + lifetime

priceMonthly:         1900    (€19/mo)
priceYearly:          19000   (€190/yr, "2 months free")
priceOneTime:         150000  (€1,500 lifetime)
accessDurationMonths: null    (lifetime = forever)

Three picker rows — monthly recurring, annual recurring, one-time lifetime. The buyer picks one; the chosen billingCycle is persisted on the application so the downstream Stripe Checkout session matches.

Example: single-cycle installment-only tier

installmentTotalPrice:     99000   (€990 total)
installmentCount:          12      (12 monthly charges)
installmentIntervalMonths: 1
accessDurationMonths:      12
installmentRenewsAnnually: false

One row in the picker — "Pay in 12× · €82.50/month · €990 total · 12 month access". After the 12th charge clears, the buyer keeps access until month 12, then expires. No auto-renew.

4. The full buyer flow

The apply flow is the same regardless of the chosen cycle; the billing-shape branch happens at Stripe Checkout creation.

Apply page
  ├─ Buyer picks tier
  ├─ Picker shown if availableCycles.length > 1
  ├─ Buyer picks payment plan (billingCycle)
  ├─ Buyer fills the segment's form
  ├─ Application submitted (status: PAYMENT_PENDING)
  ├─ Browser redirects to Stripe Checkout for the chosen plan
       ↓
Stripe Checkout
  ├─ Buyer pays
  ↓
Stripe webhook: checkout.session.completed
  ├─ Application status → APPROVED
  ├─ Customer + subscription identifiers stamped
  ├─ For INSTALLMENT_PLAN: the live subscription is bounded to
  │   end after N charges
  ├─ Invitation email fires (or the corresponding webhook fires,
  │   if Cobuntu's email automation is disabled)
       ↓
Buyer follows the email link → sign-in
  ├─ Sign-in detects "approved, no account yet" and renders a
  │   "set password" card inline
  ├─ Buyer sets password; account is created and linked to the
  │   approved membership
  └─ Buyer is logged in, member of the community

The cycle then runs forward on Stripe's clock — each invoice.paid event updates the remaining-installments counter, and for tiers configured to auto-renew, Cobuntu rotates the buyer onto a fresh Stripe subscription before the access window expires.

5. Cancellation semantics

A buyer cancels from the membership page → Cancel Subscription. What happens depends on the cycle:

cancelAtPeriodEnd: true is the flag that opts the membership out of the next renewal. A buyer who hits Cancel on a renewing installment plan can still undo cancellation before the access window ends to resume the recurring contract.

6. Refunds and billing documents

Every membership payment produces an invoice, and any refund produces a credit note. Both are available to the buyer and to community leaders.

Refunding a membership payment

A community leader with billing permissions can refund a membership payment while it is still in the escrow window — the holding period before the money is paid out to the community. Once that window has passed the funds have settled, and a refund has to be escalated to Cobuntu support.

A refund is always for the full payment amount. When a membership payment is refunded:

• The buyer is refunded to their original payment method.
• A credit note is generated and emailed to the buyer.
• The membership ends and access is revoked. For an installment plan, refunding a paid installment stops the plan — there is no separate "cancel" step.

Leaders issue refunds from the member's detail page (per payment) or from the Sales page (per sale). Both surfaces only offer the action while the payment is still refundable.

Where buyers find their documents

Buyers see their invoices and credit notes under My orders, reachable from the Receipts & invoices link on their membership page. Each row links to the hosted PDF, and filtering by Memberships narrows the list to membership payments.

Refunds that settle asynchronously — for example SEPA bank debits — show as pending until the bank confirms. The credit note and email follow once the refund completes.

7. Currencies

Three different scopes are in play; they don't all match up:

Supported currencies (19)

Use one of these ISO-4217 codes when configuring a tier:

USD  US Dollar             EUR  Euro                GBP  British Pound
CAD  Canadian Dollar       AUD  Australian Dollar   JPY  Japanese Yen
CHF  Swiss Franc           NZD  New Zealand Dollar  SGD  Singapore Dollar
HKD  Hong Kong Dollar      SEK  Swedish Krona       NOK  Norwegian Krone
DKK  Danish Krone          MXN  Mexican Peso        BRL  Brazilian Real
INR  Indian Rupee          KRW  South Korean Won    PLN  Polish Złoty
ZAR  South African Rand

Symbol formatter coverage (8)

The receipt + admin + buyer-facing formatters explicitly render a symbol for: EUR € · USD $ · GBP £ · BRL R$ · CHF CHF · CAD CA$ · AUD A$ · JPY ¥. Other supported codes show the raw amount.

Stripe

Stripe accepts ~135 currencies; we don't validate against this list at the boundary. Stick to the 19 above unless you're willing to debug formatting yourself.

Important: all price fields are in the smallest currency unit (cents for EUR/USD/GBP, yen for JPY). priceMonthly: 1900 means €19.00, not €1,900. The only exception is zero-decimal currencies (JPY, KRW) where the field equals the displayed value.

8. Founding-member rates

A tier can offer a founding rate — a discounted price for the first N buyers who join. Configure on the tier:

• foundingPriceMonthly / foundingPriceQuarterly / foundingPriceYearly — the discounted prices (in the smallest currency unit).
• foundingMemberCap — max number of buyers eligible for the discount. Once reached, new buyers see the regular price.
• foundingLockMonths — how many months a founding buyer keeps their discount before rolling to the regular price. Leave unset for a lifetime lock.

Founding rates apply only to the recurring price fields — installment plans don't have a founding alternative.

9. Replacing Cobuntu's emails with your own

Every customer-facing membership email Cobuntu sends is delivered by a [System] automation that listens to one of the membership webhook events. The data the email template uses is also in the webhook payload, so you can disable the automation and dispatch the email from your own ESP / CRM workflow instead.

To disable a Cobuntu-sent email:

1. Admin → Automations
2. Find the [System] flow (e.g. [System] Application approved)
3. Set its status to DRAFT or PAUSED

The lifecycle event continues to fire (so your webhook still receives the payload). Only Cobuntu's email side-effect is suppressed.

10. Related references

• REST API — Segments — list/read/update/submit endpoints
• REST API — Members — approve/reject/ban/kick
• Webhooks — Memberships events — the member.* and application.* events
• Webhooks — Subscriptions events — the subscription.* and tier.changed events
• Community config — accessibility (OPEN / APPLICATION / INVITE_ONLY) determines whether a paid tier requires admin review before payment
• Auth & page access — how the apply, sign-in, and membership pages compose around the buyer flow