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:
What's under the hood
The building blocks you'll use in Village
Understand what you can do with them:
Examples of incentive programs
Examples of segmentation programs
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.
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.
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
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.
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
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.
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.
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
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
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.
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
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
Read our User Segmentation Playbook to see segmentation in action->
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.
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:
Watching the video walkthrough below to familiarize yourself with Village
Reading through some of our Guides that walk through examples of rule creation in action->
Last updated
