Create Loyalty Rules using API

Learn how to create different types of loyalty rules through the API with the correct parameters and metadata

Overview

Loyalty rules define how users earn points, multipliers, or badges in your loyalty program. Each rule type has specific requirements for parameters, metadata, and configuration. This guide covers all available rule types and their required fields.

Common Parameters

All loyalty rules share these common parameters:

organizationId · string · required

The organization ID that owns this rule.

websiteId · string · required

The website ID where this rule will be applied.

name · string · required

The name of the loyalty rule (max 255 characters).

description · string

Optional description of the rule.

type · LoyaltyRuleType · required

The type of loyalty rule. See available types below.

frequency · LoyaltyRuleFrequency · required

How often eligibility is checked. Options: once, daily, weekly, monthly, immediately.

interval · LoyaltyRuleInterval

How often users can earn rewards. Options: once, daily, weekly, monthly, unlimited, custom.

startTime · ISO8601 string · required

When the rule becomes active (ISO 8601 format).

endTime · ISO8601 string

Optional end time for the rule (ISO 8601 format).

rewardType · LoyaltyRuleRewardType · required

Type of reward: points, multiplier, or badge.

loyaltyCurrencyId · string · required

The ID of the loyalty currency (points) to reward.

network · NetworkType · required

The blockchain network. Options: mainnet, goerli, polygon, arbitrum, etc.

collections · Array<Collection>

Array of collection objects for NFT/token-based rules. Format: { address: string, network: NetworkType }. Optional symbol for Ultra networks.

Reward Configuration

Reward Types

Points

Reward users with points for completing actions.

amount · number · required

The number of points to reward.

loyaltyCurrencyId · string · required

ID of the currency to reward with.

Rule Types

1. Token Hold (TokenHold)

Reward users for holding specific NFTs or ERC20 tokens.

{
  "name": "Hold Blue Chip NFT",
  "description": "Reward users holding blue chip NFTs",
  "type": "TokenHold",
  "network": "ethereum",
  "collections": [
    {
      "address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
      "network": "mainnet"
    }
  ],
  "frequency": "daily",
  "interval": "daily",
  "startTime": "2024-01-01T00:00:00Z",
  "rewardType": "points",
  "loyaltyCurrencyId": "currency_123",
  "amount": 100,
  "metadata": {
    "onlyRewardExistingUser": false,
    "onlyRewardSingleTokenOwnership": false
  }
}

{
  "id": "rule_123",
  "name": "Hold Blue Chip NFT",
  "type": "TokenHold",
  "createdAt": "2024-01-01T00:00:00Z"
}

2. Bought On (BoughtOn)

Reward users for purchasing NFTs.

{
  "name": "NFT Purchase Rewards",
  "type": "BoughtOn",
  "network": "ethereum",
  "collections": [{"address": "0x...", "network": "mainnet"}],
  "frequency": "daily",
  "interval": "once",
  "startTime": "2024-01-01T00:00:00Z",
  "rewardType": "points",
  "loyaltyCurrencyId": "currency_123",
  "amount": 1000,
  "metadata": {
    "onlyRewardExistingUser": false,
    "hasNeverSold": false
  }
}

3. Sold On (SoldOn)

Reward users for selling NFTs.

metadata.hasSaleCurrency · boolean

Filter by specific sale currency.

metadata.saleCurrency · string

Currency address when hasSaleCurrency is true.

4. Mint On (MintOn)

Reward users for minting NFTs.

metadata.hasNeverSold · boolean

Only reward users who have never sold the token.

5. Token Hold ERC20 (token_hold_erc20)

Reward users for holding ERC20 tokens.

metadata.rewardPerValue · boolean

Reward based on USD value traded rather than token count.

metadata.liquidity.isLiquidityRule · boolean

Enable Uniswap liquidity tracking.

6. Check In (check_in)

Reward users for daily check-ins.

amount · number · required

Points for each check-in.

metadata.enableStreaks · boolean

Enable streak tracking for consecutive check-ins.

metadata.streakArray · Array<Streak>

Optional array of streak milestones and rewards.

Streak Configuration

streakMilestone · number · required

Number of consecutive days for this streak.

streakAmount · number · required

Points awarded for reaching this milestone.

7. Code Entry (code_entry)

Reward users for entering promo codes.

metadata.promoCodeType · PromoCodeType · required

Type: code, csv, or generate.

metadata.promoCode · string

Single shared code (when promoCodeType is code).

metadata.promoCodeCsvUrl · string

CSV URL with unique codes (when promoCodeType is csv).

metadata.promoCodeLength · number

Number of codes to generate (when promoCodeType is generate).

metadata.isRestrictedToNewUsers · boolean

Only allow new users (last 6 hours) to redeem.

8. Referred User (referred_user)

Reward users for referring others.

amount · number · required

Points for the referred user.

metadata.referrerReward · number · required

Points for the referrer.

metadata.referrerRewardLoyaltyCurrencyId · string

Currency for referrer reward.

metadata.referralRequirements.achievePoints · boolean

Require referred users to achieve points.

metadata.referralRequirements.points.amount · number

Required points when achievePoints is true.

metadata.referralRequirements.completeProfile · boolean

Require complete profile.

metadata.referralRequirements.connectTwitter · boolean

Require Twitter connection.

metadata.referralRequirements.connectDiscord · boolean

Require Discord connection.

metadata.referralRequirements.connectEmail · boolean

Require email connection.

9. External Rule (external_rule)

Custom rules managed by external services.

amount · number · required

Base points amount.

metadata.trackProgress · boolean

Track completion progress (0-100%).

metadata.range · Array<RewardAmountRange>

Range-based rewards with custom amounts.

metadata.rewardPerAction · boolean

Multiply reward by number of actions.

metadata.conditionDescription · string

Description of what the external rule tracks.

10. Points Airdrop (points_airdrop)

Airdrop points to specific users via CSV.

loyaltyUserAllotmentCsvUrl · string · required

CSV URL with wallet addresses and point amounts.

metadata.trackProgress · boolean

Track processing progress.

11. Social Media Rules

Twitter Follow (twitter_follow)

metadata.twitterUsername · string · required

Twitter account to follow.

metadata.twitterUserId · string · required

Twitter user ID of the account.

oauthCredentialsId · string · required

OAuth credentials for Twitter.

Twitter Like (twitter_like)

metadata.twitterUsername · string · required

Account that posted the tweet.

metadata.twitterUserId · string · required

Twitter user ID.

oauthCredentialsId · string · required

OAuth credentials.

Drip X New Tweet (drip_x_new_tweet)

metadata.checkText · string | Array<string>

Text that must be included in the tweet.

metadata.requirePostLink · boolean

Require users to submit post link (default: true).

metadata.requirePostMediaLink · boolean

Require post to include media.

TikTok Post (tiktok_post)

metadata.checkText · string | Array<string>

Text to check in post.

metadata.requirePostLink · boolean

Require post link submission.

metadata.rewardCriteria · LoyaltyPostRewardCriteria

IMPRESSIONS_COUNT or ELIGIBLE_POST.

12. Discord Rules

Connected Discord (connected_discord)

metadata.discordServersToJoin · Array<DiscordServer>

Servers users must join.

Discord Server Structure

id · string · required

Discord server ID.

channels · Array<Channel>

Channels to verify activity in.

roles · Array<Role>

Optional roles to verify.

13. Liquidity Rules

Uniswap V2 Liquidity (liquidity_uniswap_v2)

Uniswap V3 Liquidity (liquidity_uniswap_v3)

metadata.liquidity.network · NetworkType · required

Chain for liquidity pools.

metadata.liquidity.protocol · string · required

Protocol identifier (e.g., “uniswap-v2/eth-usdc”).

metadata.liquidity.pools · Array<Pool>

Array of liquidity pool addresses.

metadata.liquidity.calculationType · LiquidityCalculationType · required

fixed or custom.

metadata.liquidity.liquidityPerDay · number

USD value per day (when calculationType is fixed).

metadata.liquidity.customFunction · string

Custom calculation formula (when calculationType is custom).

amount · number · required

Base points for the reward.

14. Smart Contract Event (smart_contract_event)

Reward based on smart contract events.

collectionAddress · string · required

Contract address to monitor.

metadata.smartContract.event · string

Event signature to track.

metadata.smartContract.criteria · SmartContractCriteria

everyEvent or specify conditions.

metadata.smartContract.params · Array<Param>

Event parameter filters.

metadata.smartContract.addressMapping · string

Address parameter name in event.

15. Swap (swap)

Reward users for token swaps.

metadata.swap.provider · string

any, relay, or lifi.

metadata.swap.relayReferrerId · string

Relay referrer ID when provider is relay.

metadata.swap.tokenMode · string

any or specific.

metadata.swap.swappedToChain · number | string

Chain ID or any.

metadata.swap.swappedToTokens · Array<Token>

Specific tokens when tokenMode is specific.

metadata.swap.requireCrossChainSwap · boolean

Require cross-chain swaps.

metadata.swap.trackTokenAmount · boolean

Track by token amount instead of USD.

16. Poll (poll)

Interactive poll rule.

question.text · string · required

Poll question text.

question.choices · Array<Choice>

Answer choices.

question.allowMultipleAttempts · boolean

Allow users to vote multiple times.

17. Quiz (quiz)

Quiz with single correct answer.

question.text · string · required

Question text.

question.choices · Array<Choice>

Answer options with isCorrect flag.

question.isCorrect · boolean · required

Exactly one choice must be correct.

18. Shopify Spend (shopify_spend)

Reward for Shopify store purchases.

shopifyStoreUrl · string · required

Shopify store domain.

shopifyStoreAccessToken · string · required

Shopify admin API access token.

metadata.range · Array<RewardAmountRange>

Range-based rewards by purchase amount.

Range-Based Rewards

Some rules support range-based rewards with tiered amounts:

metadata.range · Array<RewardAmountRange>

Array of reward ranges.

startRange · number · required

Minimum value for this range.

endRange · number · required

Maximum value (use Number.MAX_SAFE_INTEGER for unlimited).

amount · number · required

Points awarded for this range.

loyaltyBadgeId · string

Optional badge for this range.

Range Examples

NFT Token Hold

"metadata": {
  "range": [
    {
      "startRange": 1,
      "endRange": 10,
      "amount": 100
    },
    {
      "startRange": 11,
      "endRange": 50,
      "amount": 500
    },
    {
      "startRange": 51,
      "endRange": 9223372036854775807,
      "amount": 1000
    }
  ]
}

ERC20 Token Hold (Multiplier)

"metadata": {
  "range": [
    {
      "startRange": 1,
      "endRange": 9223372036854775807,
      "amount": 1.5
    }
  ],
  "isTokenHoldMultiplier": true
}

Advanced Configuration

Max Reward Limits

maxAmountPerInterval · number

Maximum points users can earn in the interval.

maxAmountInterval · LoyaltyRuleMaxAmountInterval

Interval period: daily, weekly, monthly.

Claim Type

claimType · LoyaltyRuleClaimType

manual (user must claim) or auto (auto-rewarded).

Reward Lifetime

rewardLifetime · LoyaltyRuleRewardLifetime

For multipliers/badges: permanent (never removed) or dynamic (removed if requirements not met).

Airdrop Duration

effectiveStartTime · ISO8601

When airdrop becomes effective.

effectiveEndTime · ISO8601

When airdrop ends.

Validation Examples

Basic Points Rule

{
  "organizationId": "org_123",
  "websiteId": "website_456",
  "name": "Daily Login",
  "type": "check_in",
  "frequency": "daily",
  "interval": "daily",
  "startTime": "2024-01-01T00:00:00Z",
  "rewardType": "points",
  "amount": 10,
  "loyaltyCurrencyId": "currency_789",
  "network": "ethereum",
  "metadata": {}
}

NFT Hold with Custom Rewards

{
  "organizationId": "org_123",
  "websiteId": "website_456",
  "name": "Hold Premium NFT",
  "type": "TokenHold",
  "network": "mainnet",
  "collections": [{
    "address": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
    "network": "mainnet"
  }],
  "frequency": "daily",
  "interval": "daily",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-12-31T23:59:59Z",
  "rewardType": "points",
  "amount": 100,
  "loyaltyCurrencyId": "currency_789",
  "metadata": {
    "hasCustomRewardsUrl": true,
    "customRewardsApiUrl": "https://api.example.com/rewards",
    "customRewardsApiKey": "key_xyz"
  }
}

Social Quest with Range Rewards

{
  "organizationId": "org_123",
  "websiteId": "website_456",
  "name": "Tweet Challenge",
  "type": "drip_x_new_tweet",
  "network": "ethereum",
  "frequency": "daily",
  "interval": "unlimited",
  "startTime": "2024-01-01T00:00:00Z",
  "rewardType": "points",
  "loyaltyCurrencyId": "currency_789",
  "metadata": {
    "checkText": ["#project", "launch"],
    "requirePostLink": true,
    "requirePostMediaLink": false,
    "range": [
      {
        "startRange": 1,
        "endRange": 5,
        "amount": 10
      },
      {
        "startRange": 6,
        "endRange": 20,
        "amount": 50
      },
      {
        "startRange": 21,
        "endRange": 9223372036854775807,
        "amount": 100
      }
    ]
  }
}

Error Handling

All required fields must be provided. Missing required fields will result in a 400 Bad Request error with details about which fields are missing.

Range values must not overlap. The start range should be less than or equal to the end range for each range entry.

For Ultra networks (Ultra/UltraTestnet), the collection address format is address::symbol. For example: accountname::TOKEN.

Use the loyaltyCurrencyId field consistently across rules to ensure proper currency management in your loyalty program.

Rule Type Limitations and Restrictions

Multiplier Reward Type Support

The multiplier reward type is NOT supported for the following rule types:

• check_in
• link_click
• referred_user
• points_airdrop

Only points and badge reward types are available for these rules.

Claim Type Support

Different rule types support different claim types (manual vs auto-reward):

Manual Only

These rules require users to manually claim rewards:

• check_in
• text_input
• poll
• quiz
• create_partner_account
• telegram_join
• drip_x_follow
• drip_x_tweet
• drip_x_new_tweet
• swap

Reward Lifetime Options

The rewardLifetime field (for multipliers and badges) has different support levels:

Permanent Only

Most rules only support permanent lifetime where rewards never expire:

• check_in
• twitter_followers
• Retweet
• BoughtOn, SoldOn, MintOn
• twitter_like, twitter_comment, twitter_post_hashtag
• profile_completed, referred_user
• poll, quiz
• Most social and connection rules

With permanent lifetime, once a user qualifies for the reward, they keep it forever even if they stop meeting requirements.

Dynamic & Permanent

These rules support both permanent and dynamic lifetime:

• TokenHold - Most flexible, supports both
• external_rule - Can expire if user stops meeting requirements

With dynamic lifetime, rewards are removed if the user no longer meets the requirements (e.g., sold their NFT).

Interval Restrictions

Some rules have limited interval options:

Rules with frequency: immediately typically only support interval: once or specific intervals.

Rules with frequency: none may support custom intervals.

Range-Based Rewards

Range-based rewards are ONLY supported for:

• TokenHold
• BoughtOn, SoldOn, MintOn
• token_hold_erc20
• twitter_followers (with rewardCriteria)
• external_rule (with trackProgress)
• shopify_spend

Range-based rewards require the metadata.range array. Maximum range value is Number.MAX_SAFE_INTEGER (use this for unlimited).

Network-Specific Limitations

For Ultra and UltraTestnet networks, collection addresses require a symbol suffix: address::symbol (e.g., accountname::TOKEN)

Token Holdings

ERC20 token holding rules (token_hold_erc20) require network support for USD price tracking. Networks without USD support will disable the rewardPerValue option.

Liquidity Pool Limits

Liquidity rules support a maximum of 20 pools per rule, all within the same network and protocol with the same factory address.

Shopify Integration

Shopify spend rules require providing both shopifyStoreUrl and shopifyStoreAccessToken. The access token is used for one-time authentication during rule creation but is not stored.