Membership

Membership types, plans, subscriptions, and membership cards form the membership domain in Communal. This page explains what each resource represents, how they relate, and the key concepts you will encounter when building on them.

Membership types

A membership type (path /membership_types) is the sellable membership product your organization offers — "Gold Membership," "Family Pass," or "Student Annual." It carries configuration such as title, description, associated waivers, and an optional signup form. Membership types are either base memberships (standalone) or add-ons (require the member to hold a base membership first).

Membership types are long-lived catalog items. When you archive one it becomes inactive and hidden from new purchases, but existing subscribers keep their access until their subscription expires.

Plans

A plan is a pricing tier within a membership type. A single membership type can offer multiple plans — for example a monthly plan at $25/month and an annual plan at $250/year. Each plan has its own:

• Amount — the price charged per billing cycle
• Interval — the billing frequency (monthly, yearly, etc.)
• Pricing type — fixed (set price), user_specifies (pay-what-you-want), or lifetime (one-time purchase, no renewal)
• Status — whether the plan is active and purchasable
• Max beneficiaries — how many additional family members the plan covers (null means unlimited)

Plans are embedded within membership type responses — you don't query them separately.

Subscriptions

A subscription represents a specific member's active membership. When someone purchases a plan, Communal creates a subscription that tracks their billing state, expiration date, and renewal preferences. Subscriptions are managed through the Stripe integration and are not directly exposed as an API resource you query — they surface through user and membership type relationships.

Key subscription states are active (the member has access), expiring (approaching ends_at and eligible for renewal), and expired (past the expiration date).

Membership cards

A membership card is a digital card delivered to members via email. Cards can be generated for Apple Wallet, Google Wallet, or as a PDF. The card's visual layout is configured through a template with overlay fields (text, QR codes) positioned on a background image.

The API exposes a single card delivery endpoint (path /membership_cards/send) rather than full CRUD on card templates. You send a card by providing user identification and optional profile data; Communal generates the card from the configured template and delivers it. Delivery attempts are tracked as activities — see the Track card deliveries guide.

How the pieces connect

The membership domain flows from catalog configuration to member access to card delivery:

flowchart TD
  MT["Membership type
  Gold Membership"]
  MT --> P1["Plan
  Monthly — $25/mo"]
  MT --> P2["Plan
  Annual — $250/yr"]
  P1 --> S1["Subscription
  Jane Doe — Monthly"]
  P2 --> S2["Subscription
  John Smith — Annual"]
  MT --> MC["Membership card
  Gold Card — Apple/Google/PDF"]
  MC --> Act["Activity
  Card delivery to Jane Doe"]

Key relationships when querying the API:

• Membership type → plans — plans are always included in membership type responses as a nested plans array
• Membership type → add-ons — add-on types reference their base membership through visibility_requires_base_membership
• Membership card → membership types — a card template is linked to specific membership types it applies to
• Card delivery → activities — delivery attempts surface through the Activities endpoints with card-specific filters

Key concepts

Base vs add-on memberships

Membership types have a type of either base or addon. Base memberships are standalone — anyone can purchase them. Add-on memberships require the buyer to already hold a specific base membership. The visibility_requires_base_membership field controls whether an add-on is even visible to non-members in your storefront.

Renewal types

Memberships use one of two renewal approaches. Rolling memberships renew indefinitely on a recurring billing cycle — the member stays active as long as payment succeeds. Date-based memberships expire on a fixed end date regardless of when the member purchased, which is common for seasonal or annual memberships tied to a calendar year.

Pricing types

Plans support three pricing models: fixed (a set price the member pays), user-specifies (pay-what-you-want, useful for donations or sliding-scale memberships), and lifetime (a one-time purchase with no recurring billing).

Card delivery

When you call the card send endpoint, Communal looks up or creates the user, generates cards in the requested formats (Apple Wallet, Google Wallet, PDF — all three by default), and emails them. The response includes a request_hash for tracing, and the delivery attempt is logged as an activity you can query later for audit or support workflows.

Archiving

Archiving a membership type sets its status to inactive and hides it from new purchases. Existing subscriptions remain active — archiving does not cancel current members. Unarchiving restores the type to active status. See Create and archive membership types for the request flow and example payloads.

API naming

Concept	API path	OpenAPI tag
Membership type	/membership_types	Membership Type
Membership card (send)	/membership_cards/send	Membership Card

Plans are nested within membership type responses and do not have their own endpoint.

What's next

• Browse membership types — list membership types, view plans, and check availability
• Create and archive membership types — add catalog products or toggle archive state
• Send membership cards — deliver digital cards to members via email
• See the Membership Type and Membership Card endpoints in the API Reference for the complete field list