The Basics of Village in 15 Minutes

Understanding the building blocks of Village, and what you can do with them.

"All great things start with the right incentives."

-A Very Wise Person (who we agree with)

The purpose of this guide is to quickly get you up to speed on the different building blocks you'll encounter within Village, as well as some examples of what you can do with them.

Here you'll learn:

  1. The building blocks you'll use in Village

  2. Understand what you can do with them:

  3. Watch an optional video walkthrough

This guide is not intended to be a substitute for the more in-depth explanations you'll find throughout the knowledge base.

To get setup on Village for the first time, go to the Admin Quickstart guide ->

To learn about Village by seeing it in action, check out our Guides ->

First up, what's under the hood?

Let's start with a quick theory session on what's actually going on inside Village. You can skip this section for now if you're not in the mood for that.

You can think of Village as two separate components that work together: an Intelligence Engine, and an Execution Ledger.

The Intelligence Engine

The Intelligence Engine securely connects to activities and events that happen on your platform through Village's API or data-integrations. It listens to all these events, and decides what to do when each event happens using rules within Village. You and your team create these rules according to business logic, and Village's intelligence engine will help you along the way through recommendations and ongoing optimization. The goal of the Intelligence Engine is to drive the best action that any given individual in your ecosystem can take at any given moment to meet defined goals.

The Execution Ledger

Our execution layer is built on Village’s powerful ledger. It works to simultaneously evaluate, distribute, and reconcile complicated value flows. While the Intelligence Engine is constantly making evaluations based on data and events coming from your platform, the Execution Ledger is automatically and instantaneously performing output operations such as securely distributing incentives into users' wallets, sending comms, and segmenting users. The best part about the execution layer is that every actions it takes is fully able to be scrutinized by your team.

Understanding the building blocks

Whatever you do in Village, you'll be using the following building blocks.

1: What Rules do

Village is built on a system of logic called Rules. Everything that happens in Village is a result of a Rule being executed. The basic components of a Rule are (1) its trigger, (2) its conditions, and (3) its output operation. Triggers could be some event happening on your platform, or a defined scheduled time, and the output might be to award your users when that event happens, with a promotion, loyalty points, or many other award types. Rules can also do other things, like segment users and send comms.

Output OperationOverviewExamples

Issue Award: Rules can issue value to a user. This is called an Award, and takes many different forms - everything from monetary awards like cash, to non-monetary awards like points, benefits, or more complicated structures like bonus pools.

  • User receives $5 per task completed

  • User receives a 10% discount when a delivery is late

  • User gets gold status when they accumulate 10,000 points

  • User gets 1.5% of their referral’s sales up to $500

Segment User: Rules can add or remove users from defined Segments. Segments are groupings of similar users that can be used to personalize comms, send particular incentives to specific users, or for analysis or experimentation.

  • User is added to Los Angeles segment when they sign up in Los Angeles

  • User is added to Power User segment when they are in the top 5% of users

  • User is added to High Risk Churn segment when they are a Power User who has not transacted in last 14 days

Send Comms: Rules can send specific comms to a user based on activity, Awards received or Segments, or some combination thereof. This can be done through the end-user dashboard or through 3rd-party CRM integrations [in beta right now].

  • User receives $50 bonus and is notified by email

  • User is in High Risk Churn segment and receives re-engagement email

  • User makes first transaction and receives notification in end-user dashboard

  • User document has expired and receives text message

2: How Rules are triggered

All Rules are evaluated when a Rule ‘trigger’ occurs. Depending on what you want to achieve, there are a few different ways to trigger a Rule.

Trigger TypeOverviewExamples

Activity Triggers: the most basic trigger type. These trigger a Rule based on some defined activity (Action) or transaction (Sale) occurring on your platform

  • User signs up

  • User completes task

  • User gets 5-star rating

  • User ends session

  • User buys something for $10

  • User sells something for $5

  • User A refers user B

Goal Triggers: goals trigger a Rule when the logic defined inside the goal has been satisfied. This can include:

  • Cumulative Activity Goals: a defined number of activities across one or more activity types occurs

  • Cumulative Award Goals: a defined Award balance across one or more Awards is reached

  • Percentile Goals: a user ranks in a defined percentile for a given activity or award over a defined period

  • User completes more than 10 deliveries in a given period

  • User watches 5 videos

  • User earns over 10,000 reward points

  • User is in the top 5% of sellers this month

  • User completed over 1000 sales this year

Segment Triggers: triggers a Rule when a user joins a given Segment

  • User joins ‘predicted_churn’ segment

  • User joins ‘signed_up_no_trips’ segment

  • User joins ‘Pro Tier’ segment

  • User drops out of the ‘Pro Tier’ segment

Scheduled Triggers: while these aren't distinct trigger types, it's worth knowing that a trigger can either occur as soon as an activity occurs or an award is issued, as well as on some predefined time schedule.

  • Evaluate every Monday at midnight

  • Evaluate quarterly on the first day of the month

3: Different types of Awards

One outcome of a Rule executing is some type of value, what is called an ‘Award’ in Village, being distributed to a user. Awards can be simple one-off transfers of value, eg. a $5 bonus, or form part of much more complicated programs involving many different Rules. How an Award is configured determines how it is communicated and experienced by the end-user of your platform.

Monetary Awards

Use CaseOverviewExamples

  • For example: USD, EUR, AUD

  • Tracked on Village, and paid out through existing payment providers (eg. Stripe, Paypal), or Village’s native payment rails

  • User is paid $10 cash when a goal is achieved

  • User is paid a $1 bonus per pickup they do on weekends

  • A user is paid $1000 cash as part of a revenue share program

Non-Monetary Fungible Awards

Within Village, we distinguish between fungible awards, eg. awards like $1 or 1 point that are identical and interchangeable with each other, and unique or non-fungible awards, like a badge, a discount code, or gift card that are uniquely identifiable.

Before configuration, non-monetary awards are called 'Units' in Village; effectively a blank store of value. Depending on how they are configured, you can create the use cases below and others.

Use CaseOverviewExamples

Points: A non-monetary, point which tracks towards some other benefit or event

  • User accumulates points that track progress towards status or benefits in loyalty program

  • User accumulates points that track progress towards cash bonus

Redeemable Points: A non-monetary, point that can be redeemed for some monetary or non-monetary Award by the user

  • User accumulates points that they redeem for credits in app

  • User accumulates points that they redeem for swag

  • User accumulates points that they redeem for in ecosystem benefits

Credits: A form of redeemable point that can be exchanged on platform for the equivalent cash value goods or services

  • User receives a $10 credit towards their next purchase

Funded Units: funded units can be linked to a bonus pool and pay out a portion of the bonus pool based on how many of the units a user holds

  • User receives $1200 quarterly bonus because they earned 500 bonus points

  • Top 5% of creators get access to a 1% platform revenue share

Tokens: A generic representation of value that can be used in a variety of contexts

  • A user receives 5 tokens for participation in a protocol’s validation

Non-Monetary Unique Awards

Use CaseOverviewExamples

Badges: Markers or Awards that can be customized and awarded as a representation of progress or achievement

  • User receives ‘OG’ Award for being first 100 on the platform

  • User receives a ‘Perfect Driver’ badge after 100 5-Star ratings

Status: Milestones that can be customized and awarded based on loyalty or engagement, and unlock benefits within your platform

  • User receives Gold Status after accumulating 50,000 points

  • User receives Pro Status when they are in the top 10% of users in a given month

Benefits: Awards that can be used to unlock some form of access or capability within your platform ecosystem

  • User unlocks ‘Priority Support’ benefit when they achieve Gold Status

  • User unlocks ‘Free Shipping’ when order is over $1,000

Discounts: Award a reduction in the price of a transaction based on a percentage or fixed amount

  • A user receives a 10% discount on their purchase

  • A user receives a $10 discount on the next 5 purchases

Commission Rebates: a way to reduce the take-rate for a given supplier transaction

  • A supplier who does over $5,000 in volume per month receives a 5% commission rebate

Gift Cards: a store of value that can be redeemed on a 3rd-party platform

  • A user receives a $100 Amazon gift card for meeting a goal

Digital Assets: Awards that represent some asset, including artwork, physical asset or some other right

  • A user receives a collector’s edition digital brand print

4: How to apply conditions to rules

Before a Rule can successfully issue an Award or place a user in a Segment, it first needs to be evaluated and the conditions of the Rule satisfied. Conditions are the business logic you want to be met before executing a Rule.

ConditionOverviewExamples

Active and Qualifying Times: Rules can be configured to only execute on certain dates and times.

  • Active Times: Rules are only considered for evaluation between these times

  • Qualifying Times: activity must occur within these times and dates to qualify for the Rule

  • Execute on weekends after 10pm

  • Execute from July 1st 12AM to August 1st 12AM.

Segment Eligibility: users must be in (or not in) one or more Segments for the Rule to execute.

  • User is in ‘predicted_churn’ or ‘signed_up_no_trips’ Segments

  • User is in ‘Pro Tier’ segment but not in ‘Diamond Tier’ segment

Max Budget: you can set maximum payouts on a Rule, time period, or user basis.

  • Max $100 bonus per user per month

  • Max $10,000 total program payout over 2023

  • Max 50 loyalty points per sale

5: Specifying who the recipient is

There may be multiple users involved in an activity on your platform, so each Rule requires a recipient for the Award, communication, or segmentation. For example, John (User 1) might buy something from Jane (User 2), who was referred to your platform by Ralf (User 3). You may want to issue Awards and send comms to all three of those users in different ways, without creating multiple events.

RecipientOverviewExamples

Activity User: one or more users can be associated with a given activity. For example, you might have a buyer and a seller in a two-sided marketplace.

  • Award the seller in a transaction with loyalty points, but not the buyer

  • Give a 5% rebate to buyers in a sales transaction if they spend more than $1,000, and email the seller about the purchase

Connected User [beta]: users may be uniquely mapped (or ‘connected’) to other users. Connections allow you to expand the recipient pool in Rule logic. For example, you may want to store referrals so that you can issue an Award to a seller’s referrer every time they make a transaction. Connected users are in beta right now.

  • Award suppliers 5% of another supplier’s sales if they referred them to the platform

  • Issue a $100 bonus to a raw materials supplier when a manufacturer sells the end product

Putting the building blocks together

To see use cases in action, and get more inspiration on what you can build, check out our Guides->

1: Incentive programs

The flexibility of Village’s Rules, and their underlying Triggers, Conditions, Award, and Segment logic, means you’re able to create and automate a variety of powerful incentive structures to meet your business needs. We’ve outlined a few common structures below.

Goal Structure Examples

Use CaseOverviewExamples

DxGy Goals: Many incentive structures use one or more ‘do X, get Y’ goals. These can be used to incentivize more engagement, or any sort of valuable behavior on your platform.

  • A courier gets 500 points when they complete 100 trips this month. They get $1000 if they complete 150 trips

  • A support agent gets a ‘Pro’ badge when they answer 100 tickets with 5 star ratings

  • A driver gets $20 per hour if they are online during peak hours with an 85% completion rate

  • A contractor gets a $1000 bonus if they complete more than 40 engagements per month for 12 months

Sales goals: Common and effective compensation structures for contractors or employees distribute Awards, rebates, or benefits when users hit a given GMV or sales volume in a defined period.

  • An account manager gets $5000 when her restaurants complete over 5000 transactions in a month.

  • A driver gets 5% commission rebate when they hit 500 rides in a month

  • All contractors get a $5000 bonus if total platform sales reach $1m this quarter.

Spend goals: A user gets discounts, credits, or benefits when they hit a given spend volume across one or multiple transactions.

  • A user gets free shipping when their basket is over $100

  • A user unlocks a 20% rolling discount when they spend over $1000 in a month

Referral Structure Examples

Use CaseOverviewExamples

Simple Referrals: A one or two-sided referral that awards the same or different Award to referrer and/or referral

Eg. Simple Referral

  • User A refers user B and user A receives $20 credit

  • User A refers user B and user A receives $100 gift card and user B receives 50% discount off 1 ride.

Trailing Referrals: A referral that awards the referrer or some other defined user a percentage of the GMV, sales, or value of the referred user (and optionally a % of the GMV, sales, or value of the referrals or the initial referred user)

  • User A refers user B and receives 5% of user B’s sales up to $500

  • User A refers user B and receives 5% of user B’s transaction volume up to $100 in credits

Affiliate Structures: A 3rd-party receives a percentage of the GMV, sales, or value of the referred user, eg.

  • Affiliates

  • Brand Ambassadors

  • Other businesses

  • 3rd-party A refers 50 users to platform and receives 5% of users GMV

Commission Split: A contractor or employee receives some percentage of the business that they have originated or managed

  • An account manager received 3% of all the GMV created by their managed accounts

Bonus Pool Structures

A badge, status, or ‘funded unit’ are all able to be linked to a funding pool. When this happens, these Awards will automatically pay users an amount of the funding pool on a defined date proportionate to the total amount of linked awards they have accumulated.

Use CaseOverivew

Revenue Share: An incentive structure that can be created using funded Awards and a funding pool to pay users a percentage of a platform's revenue generated in a given period, proportionate to the total funded Awards held.

  • Users receive medallions for positive actions they do on the platform. 1% of all platform revenue is distributed to medallion holders each month, as long as they continue to be active

  • Users in Power Status receive 1 revenue share unit for every 100 trips they complete on the platform. Each month, the total pool is distributed among revenue share unit holders

Bonuses: An incentive structure that can be created using funded Awards and a funding pool that pays out a percentage of a fixed bonus pool proportionate to the total funded Awards held.

  • Each month, a company Awards $100,000 to top employees. Employees receive points based on tasks fulfilled and other valuable actions and the pool is distributed proportionate to total points held each month.

Creator Fund: An incentive structure that can be created using a funded Award and a funding pool that pays out a percentage of the fixed or variable bonus pool, proportionate to the total value brought to the platform by a creator.

  • An edtech company allocates 20% of total subscription revenue into a creator fund. Each quarter, top creators are Awarded a share of this pool based on how many times their content was accessed or engaged with.

Loyalty Programs

Use CaseOverviewExamples

Loyalty Programs: These programs use a combination of points, status, and benefits to drive engagement and retention on your platform.

  • A delivery company has four different loyalty tiers, Silver, Gold, Platinum and Black. Points are Awarded for valuable actions on the platform. When a tier is reached, certain benefits are unlocked for a user. Points can be set to expire in a given period and users must maintain a given points balance to retain status.

Subscriptions & Stored Value

Subscriptions: a recurring benefit or discount in exchange for a (recurring) upfront charge

  • A user pays $10 upfront to receive 20% off this month’s transactions

  • A user pays monthly to receive a fixed number of rides per month

Stored Value: A user is able to pay upfront for value stored on the platform that is used on future transactions

  • User uploads $100 to their wallet that is used to purchase future orders

2: Segmentation programs

Segments allow you to group similar users using Rules logic. These Rules are triggered based on activities or events on your platform. Segments are therefore a powerful way to group like individuals or track user journeys in order to deliver more personalized incentives or comms. While Segments are very flexible, some common use cases are below.

Use CaseOverviewExamples

Onboarding Funnel: Customer or supplier onboarding processes usually involve a number of steps before a customer is active. Even when they are ready to transact, users often lack an understanding of how to do so effectively. Segments can be created for each individual step in these funnels, and comms (through CRM integrations) or incentives can be created and automated to get users active.

  • A delivery platform requires 5 submitted documents before a supplier can be activated. A segment is created for each step in this process and comms automatically sent to describe the next required action. When a user gets stuck, incentives like credits or time-bound goal bonuses (do 10 deliveries in 10 days) can be automatically sent

  • A customer has signed up but hasn’t interacted with your product yet or made a purchase. Send them education materials relevant to their status in the funnel, and push some credit if they’ve been there more than 30 days

Lifecycle Management: Define user archetypes based on transaction volume, behaviors or other activity on your platform. These Segments give you up-to-the-minute visibility into user engagement, from signup to power user. You can use lifecycle Segments for automated incentives like milestone badges, status, goals, as well as for sending targeted comms or analytics.

  • A ride-share platform has 4 broad user archetypes - new user, part-time user, full-time user, power user. These can be defined and automated through Rules logic based on the activity and engagement of each user. When a user moves between different Segments, different comms, goals, or benefits are applied

Churn Prevention: Certain user behavior across different Segments can be predictive or indicative of churn. By setting up churn prevention Segments, you are able to automatically catch and correct these behaviors (for instance, decreasing engagement from a power user segment, or no transactions in X period).

  • A freelance platform has Rules set up that look for power users that have not interacted with the platform in the last 14 days. These users receive an engagement email. If these users have not interacted after 30 days, they receive a rebate on commission for their next contract

  • An eCommerce website issues a $50 credit with a 7 day expiration for users who haven’t made a purchase in the last 30 days

Personalization: Users respond better to incentives and comms when they are tailored to them. By creating Segments based on characteristics and activities a user does on your platform, you’re able to be hyper-targeted to drive the right behaviors.

  • A rideshare driver is in the ‘Los Angeles’, ‘Night-drivers’, ‘Weekend drivers’,’Churn Risk’,’2+ years’ Segments. He receives a re-engagement goal to do 50 trips between 12am-5am this weekend, alongside comms that reference he’s a loyal Los Angeles night-owl

  • A shopper on a delivery app has only ever purchased groceries, so receives a tailored promo to get a discount to try the pharmacy products

Drip Campaigns: Sometimes it’s important not to overload users when trying to educate how a product works, or when trying to foster a relationship. Similarly, specific moments - positive or negative - can be extremely important to send just the right communications, education, or recognition. These can all be automated through segmentation on Village.

  • A hourly work platform has different processes for different clients on their platform. They are able to segment and drip educational messages to their workers in the moment when activity occurs, rather than all upfront

  • A rideshare platform needs to send the right information to riders and drivers when something goes wrong. Triggered messages that listen for these events create peace of mind and prevent future issues

Percentile Cohorts: Percentile-based Rules allow you to segment users based on where they rank relative to their peers on any dimension. This is a powerful way to view and group users in order to reward behaviors or send the right communications, and these Segments are automatically updated on a defined frequency.

  • A creator platform wants to share subscription revenue with the top 10% most engaged users in a monthly period

  • A rideshare platform wants to automatically waitlist and review the lowest 5% rated drivers who have completed more than 100 trips

Waitlist Segments: Waitlist Segments can prevent users from engaging with some or all of your product based on some defined criteria.

  • A new platform wants to restrict consumer access until a given consumer has invited 5 friends

  • A delivery company wants to restrict access to its platform instantaneously for any courier who has received a serious incident tag

  • A platform restricts access to a certain feature to non-paid subscribers

Congrats! 🎉 You should have a high level understanding of how Village works, and what you can do with it.

Next up, we recommend:

Last updated