Update Loyalty Program

Modify existing loyalty program parameters including point allocation rules and tier configurations. This function allows you to update both the rewards structure and tier requirements without creating a new program.

Overview

The updateLoyaltyProgram function enables you to modify an existing loyalty program's configuration. You can update points per action, modify tier structures, or both simultaneously while preserving existing user data and loyalty passes.

import { updateLoyaltyProgram } from '@verxioprotocol/core'

// Update points per action only
const result = await updateLoyaltyProgram(context, {
  collectionAddress: publicKey('COLLECTION_ADDRESS'),
  programAuthority: context.programAuthority,
  updateAuthority: programAuthority,
  newPointsPerAction: {
    purchase: 150,    // Updated from 100
    review: 75,       // Updated from 50
    referral: 300     // New action type
  }
})

// Update tiers only
const result = await updateLoyaltyProgram(context, {
  collectionAddress: publicKey('COLLECTION_ADDRESS'),
  programAuthority: context.programAuthority,
  updateAuthority: programAuthority,
  newTiers: [
    { name: 'Bronze', xpRequired: 400, rewards: ['3% cashback'] },
    { name: 'Silver', xpRequired: 1000, rewards: ['7% cashback'] },
    { name: 'Gold', xpRequired: 2500, rewards: ['12% cashback'] }
  ]
})

Parameters

The function accepts a context object and a configuration object with the following parameters:

Parameter	Type	Required	Description
context	VerxioContext	✅	The initialized Verxio context object
collectionAddress	PublicKey	✅	The collection address of the loyalty program to update
programAuthority	Signer	✅	The program authority (must match the original authority)
updateAuthority	Signer	✅	The update authority for the program
newPointsPerAction	Record<string, number>	❌	Updated points allocation for different actions
newTiers	Array<Tier>	❌	Updated tier configuration (must include 'Grind' tier)

⚠️ Important Note

At least one of newPointsPerAction or newTiers must be provided. You cannot call this function without specifying what to update.

Tier Update Requirements

When updating tiers, you must follow these rules:

🎯 Tier Structure Rules

A tier named "Grind" with xpRequired: 0 must always exist as the first tier
Tiers must be ordered by increasing XP requirements
XP requirements must be positive numbers (except for Grind tier)
Tier names should be unique within the program
Existing users will be automatically re-evaluated against new tier thresholds

Return Value

The function returns a Promise that resolves to an object containing:

{
  signature: string    // Transaction signature confirming the update
}

Property	Type	Description
signature	string	The transaction signature confirming the program update

Usage Examples

Update Points Per Action

Modify how many points users earn for different actions:

// Increase points for purchases and add new action types
const result = await updateLoyaltyProgram(context, {
  collectionAddress: publicKey('YOUR_COLLECTION_ADDRESS'),
  programAuthority: context.programAuthority,
  updateAuthority: updateAuthority,
  newPointsPerAction: {
    purchase: 150,      // Increased from 100
    review: 75,         // Increased from 50
    referral: 200,      // New action type
    socialShare: 25,    // New action type
    newsletter: 50      // New action type
  }
})

Update Tier Structure

Modify tier requirements and rewards:

// Add new tier and adjust requirements
const result = await updateLoyaltyProgram(context, {
  collectionAddress: publicKey('YOUR_COLLECTION_ADDRESS'),
  programAuthority: context.programAuthority,
  updateAuthority: updateAuthority,
  newTiers: [
    { 
      name: 'Grind', 
      xpRequired: 0, 
      rewards: ['Welcome bonus'] 
    },
    { 
      name: 'Bronze', 
      xpRequired: 300,  // Lowered from 500 
      rewards: ['5% discount', 'Free shipping'] 
    },
    { 
      name: 'Silver', 
      xpRequired: 1000, 
      rewards: ['10% discount', 'Priority support'] 
    },
    { 
      name: 'Gold', 
      xpRequired: 2500, 
      rewards: ['15% discount', 'Exclusive access'] 
    },
    { 
      name: 'Platinum',  // New tier
      xpRequired: 5000, 
      rewards: ['20% discount', 'Personal concierge'] 
    }
  ]
})

Update Both Simultaneously

Modify both points and tiers in a single transaction:

const result = await updateLoyaltyProgram(context, {
  collectionAddress: publicKey('YOUR_COLLECTION_ADDRESS'),
  programAuthority: context.programAuthority,
  updateAuthority: updateAuthority,
  newPointsPerAction: {
    purchase: 120,
    review: 60,
    checkin: 30
  },
  newTiers: [
    { name: 'Grind', xpRequired: 0, rewards: ['Welcome'] },
    { name: 'Explorer', xpRequired: 400, rewards: ['5% off'] },
    { name: 'Adventurer', xpRequired: 1200, rewards: ['10% off'] },
    { name: 'Legend', xpRequired: 3000, rewards: ['15% off'] }
  ]
})

Verxio Protocol