Davi Developers LogoDavi Developers

Documentation

Membership Tiers and Members

Create and retire an organization's membership tiers, read a user's memberships, and manage an organization's members.

This page covers defining an organization's membership tiers, reading which memberships a user holds, and managing the memberships an organization has issued. An organization offers one or more membership tiers. A user's membership is their enrollment in one tier, with its own membership wallet and validity window. See Core Concepts for the model.

Membership tiers

Managing tiers acts on behalf of the organization, so use an org-scoped token.

MethodPathScope
GET/organizations/{organization_slug}/membership-tiersorg:tiers:read
POST/organizations/{organization_slug}/membership-tiersorg:tiers:manage
GET/organizations/{organization_slug}/membership-tiers/{tier_uuid}org:tiers:read
PATCH / DELETE/organizations/{organization_slug}/membership-tiers/{tier_uuid}org:tiers:manage

Create a tier with a name, price and interval:

curl -X POST \
  "https://api.davi.social/api/v1/organizations/ORG_SLUG/membership-tiers" \
  -H "Authorization: Bearer ORG_SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gold",
    "price_cents": 4900,
    "currency": "PHP",
    "payment_interval": "monthly",
    "description": "Priority access and perks"
  }'
FieldMeaning
price_centsThe price in minor units of currency: 4900 is ₱49.00, not ₱4,900
currencyISO 4217 code. Defaults to PHP. Every tier returns it, so render a price against the tier's own currency
payment_intervaldaily, weekly, monthly, yearly or one_time

Reading a user's memberships

GET /memberships (scope user:read) lists the authenticated user's active memberships across organizations:

curl "https://api.davi.social/api/v1/memberships" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Each entry includes organization_uuid and tier_uuid (with organization_name and tier_name alongside), joined_at, and valid_until. Check valid_until for expiry; null means the membership does not expire. With an org-scoped token, the list is filtered to that organization.

GET /organizations/{organization_slug}/memberships/{user_uuid} returns one user's active membership in a specific organization.

A user's staff role on an organization is a different relationship with a different endpoint: see Fetching an Organization.

Managing an organization's memberships

These act on behalf of the organization, so use an org-scoped token.

MethodPathPurpose
GET/organizations/{organization_slug}/membershipsList the organization's memberships
POST/organizations/{organization_slug}/membershipsEnroll a user at a tier
GET / PATCH / DELETE/organizations/{organization_slug}/memberships/{user_uuid}Read, change tier, or end a membership
POST/organizations/{organization_slug}/memberships/{user_uuid}/renewRenew a membership
GET/organizations/{organization_slug}/memberships/{user_uuid}/historyMembership history, including ended ones
GET/organizations/{organization_slug}/memberships/{user_uuid}/walletThe holder's membership wallet
GET/organizations/{organization_slug}/memberships/{user_uuid}/cardsCards issued to the holder

A membership is also created when a user claims a card that carries a membership tier.

Cancelling, renewing, restoring and moving between tiers are covered in Membership Lifecycle.

Retiring a tier

Deleting a tier does not move the memberships on it. Retire a tier in this order:

  1. PATCH the tier's visibility to private, so nobody else joins it.
  2. POST /organizations/{organization_slug}/membership-tiers/{tier_uuid}/memberships/move (scope org:tiers:manage), naming the destination tier in membership_tier_slug.
  3. DELETE the tier.

Send the move with dry_run: true first. It returns the same report and changes nothing. The report carries memberships, the skipped ones, and still_blocking_delete, which lists what would still stop step 3. This report is what the move endpoint offers over looping PATCH /organizations/{organization_slug}/memberships/{user_uuid} yourself.

The move runs in the background, so a real run answers scheduled.

Next