# Fanbases and loyalty Use Fanbases to turn people who follow, buy and show up into a community you can see and reward. A fanbase belongs to an organization. Fans join by following it or by buying a ticket, they earn points for what they do, and the points move them up tiers you set. You get a member list, an activity feed and stats, and you can message members from the same place. ## How the pieces fit | Resource | What it is | |---|---| | Fanbase | The community for one organization. It is created the first time you read it, and with the organization. | | Member | A person in the fanbase, with `total_points`, `lifetime_points` and a tier. | | Tier | A level with a name, a threshold in lifetime points and a list of perks. A fanbase has 1 to 5. | | Activity | One thing a member did, with the points it moved. | A new fanbase starts with auto-enroll on, a points multiplier of 1, a welcome bonus of 50 points and five tiers: Fan (0), Supporter (500), Superfan (1,500), VIP (5,000) and Legend (15,000). You can change all of it. A client uses them in this order: 1. A fan finds the fanbase on a public page and follows the organization. 2. Following adds the fan as a member and awards the welcome bonus. With auto-enroll on, buying a ticket for any of the organization's events adds the buyer too. Organizers can also invite people by email or import past attendees. 3. Each activity adds points, as the table below shows. 4. When lifetime points pass a tier threshold, the member moves up. Vabu sends a welcome message on WhatsApp when someone joins (if they have a phone number) and a congratulation message when they reach a new tier. 5. The organizer reads members, activity and stats, and sends messages. See [Messaging](https://docs.vabu.live/products/messaging.md). | What the fan does | Points | |---|---| | Buys a ticket | 1 point for every KES 10 paid, rounded down | | Is checked in at the door | 100 points, when the ticket email matches an account | | Follows the organization | The welcome bonus | Ticket points need auto-enroll on. The points multiplier (0.1 to 10) scales all of these. Adding a ticket to a phone wallet shows in the activity feed and earns no points. `lifetime_points` never goes down and decides the tier. Points cannot be spent through the API today. See [what's coming](https://docs.vabu.live/whats-coming.md). ## What you can call today ### Public pages and following | Method | Path | What it does | |---|---|---| | GET | `/v1/public/fanbases` | List public fanbases. Search, and sort by `popular`, `recent` or `events`. | | GET | `/v1/public/fanbases/{slug}` | Get one fanbase with links and counts. Send a user token to get `is_following`. | | GET | `/v1/public/fanbases/{slug}/events` | List the organization's events, with live, upcoming and past counts. | | POST | `/v1/creator/orgs/{org}/follow` | Follow an organization. This joins its fanbase. | | DELETE | `/v1/creator/orgs/{org}/follow` | Unfollow. The member becomes inactive. | | GET | `/v1/creator/orgs/{org}/followers` | List an organization's followers. Owners and Admins only. | The fanbase storefront is part of [Commerce](https://docs.vabu.live/products/commerce.md). ### Fanbase profile, settings and tiers | Method | Path | What it does | |---|---|---| | GET | `/v1/organizer/fanbase` | Get the fanbase profile with member, event and tier counts. | | PUT | `/v1/organizer/fanbase` | Update the name, description, contact email and links. | | POST | `/v1/organizer/fanbase/logo` | Upload a logo. | | POST | `/v1/organizer/fanbase/cover` | Upload a cover image. | | GET | `/v1/organizer/fanbase/settings` | Read `enabled`, `auto_enroll`, `points_multiplier` and `welcome_bonus_points`. | | PUT | `/v1/organizer/fanbase/settings` | Change any of those. Send only what changes. | | GET | `/v1/organizer/fanbase/tiers` | List tiers with thresholds and perks. | | PUT | `/v1/organizer/fanbase/tiers` | Replace the tiers. Send 1 to 5. | | GET | `/v1/organizer/fanbase/stats` | Read members, new members, points awarded and tier split for `7d`, `30d`, `90d` or `12m`. | ### Members and activity | Method | Path | What it does | |---|---|---| | GET | `/v1/organizer/fanbase/members` | List members. Search, filter by tier and sort by name, points or join date. | | GET | `/v1/organizer/fanbase/members/export` | Download members as a CSV file. | | POST | `/v1/organizer/fanbase/members/invite` | Add up to 100 people by email. They need an account already. | | POST | `/v1/organizer/fanbase/members/sync` | Add past attendees of your events who have an account. | | GET | `/v1/organizer/fanbase/members/activity` | Read the activity feed for all members. Filter by period and `activity_type`. | | GET | `/v1/organizer/fanbase/members/{member_id}/activity` | Read one member's recent activity. | Full parameters and responses are in the [API reference](https://docs.vabu.live/api.md). Here is how to double the points your fans earn: ```sh curl -X PUT https://api.vabu.live/v1/organizer/fanbase/settings \ -H "Authorization: Bearer $USER_TOKEN" \ -H "X-Tenant-Code: $TENANT_CODE" \ -H "Content-Type: application/json" \ -d '{ "points_multiplier": 2 }' ``` ## Points from Streams Fans earn points for watching a live stream or an asset and for paid moments: - A full watch is 80 percent of the live stretch (or of the asset's length). It earns 25 points once per fan and stream. Watch time adds up across sessions. - A paid moment in KES earns one point per KES 10. If you cancel the moment, the points go back. Points go to the fanbase of the stream's organization. Set `organization_id` in the live stream's `metadata`; if you leave it out, the tenant's only fanbase is used. A fan earns points only when the `customer` you pass to Streams is their Vabu user id (`usr_...`) in your tenant. A customer that is only your own reference earns nothing yet. ## Messages that bring fans back Both are off until you turn them on in your tenant settings (`streams.live_now_messages`, `streams.clip_ready_messages`). They go out in live mode only, by WhatsApp first and by text message if WhatsApp is off or fails. - **Live now.** When a live stream goes live, members of the organization's fanbase who opted in (`notifications.live_now` is `true` on the member, and `notifications.opt_out` is not) get one message per stream per day. - **Clip ready.** When the clip of a paid moment is ready, the fan who paid gets it, if they are a Vabu user in your fanbase with `notifications.clip_ready` on. Set `streams.templates.live_now` and `streams.templates.clip_ready` to your approved WhatsApp template names (defaults `streams_live_now_v1`, `streams_clip_ready_v1`). Set `streams.watch_url` and `streams.clip_url`, with `{id}` where the stream or clip id goes, to add a link. ## Calling these endpoints The three public reads take only `X-Tenant-Code`. The single fanbase read also takes an optional user token. Every other route takes a signed-in user token (`Authorization: Bearer ...`, a Vabu ID or Payd ID token) plus `X-Tenant-Code`, in live mode. Organizer routes also accept an optional `X-Organization-Id` header to pick which organization you act for. Test keys and publishable keys are refused on these routes today. See [which credentials each endpoint takes](https://docs.vabu.live/concepts/keys-and-scopes.md#which-credentials-each-endpoint-takes). Any active member of the organization can read fanbase data. Changing the profile, settings or tiers, and inviting or importing members, needs the Owner or Admin role. For paging and error shapes, see [pagination](https://docs.vabu.live/concepts/pagination.md) and [errors](https://docs.vabu.live/concepts/errors.md). ## Related - [Messaging](https://docs.vabu.live/products/messaging.md) to email, text or WhatsApp your members. - [Events](https://docs.vabu.live/products/events.md) for the tickets and check-ins that earn points. - [How products work together](https://docs.vabu.live/products/how-products-work-together.md) for the loyalty loop across products.