Guides

Rewards Display Guide

Learn how to display Bitcoin rewards to users with accurate, clear messaging. This guide explains what each field means and how to present rewards in your UI.

See it in action

Visit our shop page to browse all merchants, or check out an example business page.

Understanding Reward Fields

The rewards object contains the raw data for building custom displays:

Field	Meaning
`headlinePercent`	What to advertise. Base rate + first purchase bonus. This is the best rate a new customer gets via your referral link.
`basePercent`	Ongoing rate. What customers earn on every purchase after their first.
`maxPercent`	VIP ceiling. The highest rate possible if VIP tiers exist.
`hasVipTiers`	Whether customers can earn higher rates through VIP progression.

First Purchase Bonus

When a customer clicks your referral link and makes their first purchase, they receive an extra bonus on top of the base rate:

// The headline is calculated as:
headlinePercent = basePercent + referralBonus

// Example: 3% base + 2% referral bonus = 5% headline
// Customer gets 5% on first purchase, 3% on every purchase after

Important: The referral bonus only applies when the customer uses your referral link. After their first purchase, they earn the basePercent on all subsequent purchases.

VIP Tiers

Some businesses offer VIP tiers where customers earn higher rates based on their total spending. When hasVipTiers is true:

basePercent is typically the entry-level tier rate
maxPercent is the highest tier rate achievable
Customers progress through tiers as they spend more

Display this as: "Up to {maxPercent}% back for VIP customers"

Code Examples

Here's how to build reward displays in plain JavaScript:

Headline Calculation

const headlinePercent = basePercent + (referralBonus || 0);

Conditional Display Text

function getDisplayText(rewards) {
  const { headlinePercent, basePercent, maxPercent, hasVipTiers, referralBonus } = rewards;

  // Primary text (always show this)
  const primary = `${headlinePercent}% Bitcoin Back`;

  // Secondary text (context)
  let secondary = null;
  if (referralBonus > 0) {
    secondary = `${basePercent}% ongoing after first purchase`;
  } else if (hasVipTiers) {
    secondary = `Up to ${maxPercent}% with VIP`;
  }

  return { primary, secondary };
}

Full Display with All Scenarios

function formatRewardsDisplay(business) {
  const { rewards } = business;
  const lines = [];

  // Main reward
  lines.push(`${rewards.headlinePercent}% back in Bitcoin`);

  // Context for first purchase bonus
  if (rewards.referralBonus > 0) {
    lines.push(`On your first order — ${rewards.basePercent}% after that`);
  } else if (rewards.hasVipTiers) {
    lines.push(`On every purchase, up to ${rewards.maxPercent}%`);
  } else {
    lines.push(`On every purchase`);
  }

  // Optional: VIP tiers
  if (rewards.hasVipTiers) {
    lines.push(`Up to ${rewards.maxPercent}% back for VIP customers`);
  }

  // Optional: Bitcoin payment bonus
  if (rewards.btcPayBonus?.enabled) {
    lines.push(`+${rewards.btcPayBonus.bonus}% when paying with Bitcoin`);
  }

  // Optional: Social rewards
  if (rewards.socialRewards?.enabled) {
    lines.push(`Earn up to ${rewards.socialRewards.totalSats} sats for social follows`);
  }

  return lines;
}

Our React Implementation

Here's how we implement these patterns in our own React shop:

Headline Calculation

// How we calculate the customer's headline percentage
const basePercent = rewardsConfig?.baseRewards.minPercentage ?? 0;
const referralBonus = (rewardsConfig?.referrals.enabled &&
  rewardsConfig?.referrals.referredRewardType === 'percentage')
  ? (rewardsConfig?.referrals.referredReward ?? 0)
  : 0;
const customerHeadlinePercent = referralBonus > 0
  ? basePercent + referralBonus
  : basePercent;

Conditional Display

// How we show different text based on reward configuration
{referralBonus > 0
  ? `${customerHeadlinePercent}% back on first purchase (${basePercent}% ongoing)`
  : `${basePercent}% back on every purchase`}

VIP Tier Display

{rewardsConfig?.baseRewards.hasVipTiers && (
  <span>Up to {rewardsConfig.baseRewards.maxPercentage}% back for VIP customers</span>
)}

Bitcoin Payment Bonus

{rewardsConfig?.btcPayBonus?.enabled && (
  <span>+{rewardsConfig.btcPayBonus.bonus}% bonus for Bitcoin payments</span>
)}

Social Rewards

{rewardsConfig?.socialRewards?.enabled && (
  <span>Up to {rewardsConfig.socialRewards.totalSats.toLocaleString()} sats for social follows</span>
)}

Display Recommendations

Do

Show headlinePercent prominently — it's the hook
Always include context about ongoing rates
Indicate if first purchase bonus applies
Make VIP tiers discoverable (not hidden)
Show social rewards as a separate, optional bonus

Don't

Say "Always get X%" when X includes first purchase bonus
Hide the ongoing rate after first purchase
Imply social rewards are recurring (they're one-time)
Combine shopping % and social sats in one number
Show maxPercent as the default rate

Example Scenarios

Scenario 1: Simple (base rewards only)

headlinePercent: 3, basePercent: 3, hasVipTiers: false

"3% back on every purchase"

Scenario 2: First purchase bonus

headlinePercent: 5, basePercent: 3, referralBonus: 2

"5% back in Bitcoin"
"3% ongoing after first purchase"

Scenario 3: VIP tiers

headlinePercent: 3, basePercent: 3, maxPercent: 8, hasVipTiers: true

"3% back in Bitcoin"
"Up to 8% with VIP"

Scenario 4: Everything

headlinePercent: 5, basePercent: 3, maxPercent: 8, hasVipTiers: true, btcPayBonus: 2, socialRewards.totalSats: 500

"5% back in Bitcoin"
"3% ongoing, up to 8% with VIP"
"+2% for Bitcoin payments"
"Earn up to 500 sats for social follows"