Skip to main content
POST
/
api
/
loyalty
/
rules
JavaScript
import SnagSolutions from '@snagsolutions/sdk';

const client = new SnagSolutions({
  apiKey: 'My API Key',
});

const rule = await client.loyalty.rules.create({
  amount: '10.5',
  effectiveEndTime: '2024-12-31T23:59:00Z',
  effectiveStartTime: '2024-01-01T00:00:00Z',
  endTime: '2024-12-31T23:59:00Z',
  frequency: 'daily',
  loyaltyCurrencyId: '456e1234-e89b-12d3-a456-426614174003',
  metadata: {},
  name: 'Referral Bonus Rule',
  organizationId: '123e4567-e89b-12d3-a456-426614174001',
  startTime: '2024-01-01T00:00:00Z',
  type: 'Bonus',
  websiteId: '123e4567-e89b-12d3-a456-426614174002',
});

console.log(rule.id);
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organizationId": "123e4567-e89b-12d3-a456-426614174001",
  "websiteId": "123e4567-e89b-12d3-a456-426614174002",
  "backgroundAssetUrl": "https://example.com/background.png",
  "name": "Referral Bonus Rule",
  "description": "A loyalty rule rewarding users for referrals.",
  "network": "mainnet",
  "type": "Bonus",
  "frequency": "daily",
  "interval": "weekly",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-12-31T23:59:00Z",
  "effectiveStartTime": "2024-01-01T00:00:00Z",
  "effectiveEndTime": "2024-12-31T23:59:00Z",
  "amount": "<any>",
  "customRewardsCsvUrl": "https://example.com/rewards.csv",
  "customRewardsApiUrl": "https://api.example.com/rewards",
  "subscriptionId": "sub12345",
  "metadata": {
    "isCheckInOnEveryTxn": true,
    "onlyNonListed": true,
    "hasPaidFullRoyalty": false,
    "royaltyAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "royaltyPercentage": 5,
    "hasVerifiedTwitter": true,
    "onlyRewardExistingUser": true,
    "hasNeverSold": false,
    "onlyNative": true,
    "hasFillSource": true,
    "fillSource": "opensea.io",
    "liquidity": {
      "network": "mainnet",
      "protocol": "Uniswap V2",
      "onlyRewardInRangeLiquidity": true,
      "liquidityPerDay": 1000,
      "customFunction": "x = y * 1000",
      "calculationType": "fixed",
      "pools": [
        {
          "id": "0xabcdefabcdefabcdefabcdefabcdefabcdef"
        }
      ]
    },
    "twitterUsername": "@example_user",
    "twitterUserId": "1234567890",
    "twitterHashtag": "#loyalty",
    "enableVerifiedMultiplier": true,
    "verifiedMultiplier": 1.5,
    "isMultiplierApplied": true,
    "onlyKnownUsers": false,
    "firstReferralReward": 10,
    "referrerReward": 50,
    "referrerRewardLoyaltyCurrencyId": "1234567890",
    "secondReferralReward": 5,
    "enableStreaks": true,
    "promoCode": "PROMO123",
    "promoCodeType": "code",
    "promoCodeLength": 10,
    "promoCodeCsvUrl": "https://example.com/promo_codes.csv",
    "enableJoinDiscordServers": true,
    "discordServersToJoin": [
      {
        "id": "123456789012345678",
        "channels": [
          {
            "id": "987654321098765432",
            "text": "Hello",
            "emojis": [
              {
                "id": "1f600"
              }
            ]
          }
        ],
        "roles": [
          {
            "id": "role123"
          }
        ]
      }
    ],
    "streakArray": [
      {
        "streakMilestone": 5,
        "streakAmount": 10
      }
    ],
    "dripQuestsToComplete": [
      {
        "id": "drip123"
      }
    ],
    "collection": [
      {
        "address": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
        "network": "mainnet",
        "multiplier": 2
      }
    ],
    "range": [
      {
        "startRange": 1,
        "endRange": 10,
        "amount": 5,
        "loyaltyBadgeId": "badge123",
        "loyaltyMultiplierAmount": 1.5
      }
    ],
    "customRewardsApiKey": "api-key-1234",
    "link": "https://example.com",
    "socialPlatform": "X(Twitter)",
    "socialPlatformName": "Twitter",
    "socialPlatformLogo": "https://example.com/logo.png",
    "rewardPerImpression": true,
    "minQty": 1,
    "maxQty": 10,
    "snapshotProposals": [
      {
        "id": "proposal123",
        "space": "space123"
      }
    ],
    "cta": {
      "label": "Click Here",
      "href": "https://example.com"
    },
    "hasSaleCurrency": false,
    "isTokenHoldMultiplier": true,
    "saleCurrency": "USD",
    "isRetroactive": true,
    "timeDelayToVerifySeconds": 300,
    "referralRequirements": {
      "points": {
        "amount": 50,
        "loyaltyCurrecyId": "currency123"
      },
      "achievePoints": true,
      "completeProfile": false,
      "connectTwitter": true,
      "connectDiscord": true,
      "connectEmail": true
    },
    "multiplierLoyaltyCurrencyIds": [
      "currency123",
      "currency456"
    ],
    "verifyPlaceHolderText": "Enter your verification code here.",
    "verificationTextMinimumLength": 10,
    "buttonText": "Verify Now",
    "telegramChannelId": "telegram-channel-123",
    "twitterAccountUrl": "https://twitter.com/example_user",
    "twitterPostUrl": "https://twitter.com/example/status/1234567890",
    "checkLike": true,
    "checkRepost": true,
    "checkComment": true,
    "checkText": "loyalty",
    "requirePostLink": true,
    "requirePostMediaLink": true,
    "rewardCriteria": "IMPRESSIONS_COUNT",
    "smartContract": {
      "contractId": "123e4567-e89b-12d3-a456-426614174000",
      "event": "Transfer",
      "type": "event",
      "criteria": "everyEvent",
      "params": [
        {
          "name": "value",
          "condition": ">=",
          "value": "100"
        }
      ],
      "addressMapping": "0x123...789",
      "amountMultiplier": {
        "valueMapping": "amount"
      }
    },
    "walletType": "evm",
    "imageUrl": "https://example.com/image.png",
    "trackAllContracts": true,
    "onlyRewardSingleTokenOwnership": true,
    "skipMultiplier": true,
    "completeProfileConditions": {
      "twitter": true,
      "discord": false
    },
    "steamAppId": "1234567890",
    "trackProgress": true,
    "rewardPerAction": true,
    "rewardByBatch": true,
    "batchSize": 100,
    "youtubeVideoId": "1234567890",
    "youtubeChannelId": "1234567890",
    "isRestrictedToNewUsers": false,
    "rewardBadgePerRange": false,
    "swap": {
      "provider": "any",
      "relayReferrerId": "<string>",
      "tokenMode": "any",
      "swappedToChain": 123,
      "requireCrossChainSwap": true,
      "swappedToTokens": [
        {
          "address": "<string>",
          "chainId": "<string>"
        }
      ],
      "trackTokenAmount": true
    },
    "rewardPerValue": false,
    "conditionDescription": "Complete the specific task on external platform",
    "directRpc": false,
    "erc20Type": "erc20"
  },
  "collectionAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "collections": [
    {
      "address": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
      "network": "mainnet",
      "symbol": "COLL"
    }
  ],
  "hideInUi": false,
  "showBeforeStart": false,
  "isRequired": true,
  "oauthCredentialsId": "123e4567-e89b-12d3-a456-426614174003",
  "loyaltyCurrencyId": "456e1234-e89b-12d3-a456-426614174003",
  "loyaltyRuleGroupId": "123e4567-e89b-12d3-a456-426614174004",
  "rewardType": "points",
  "loyaltyBadgeId": "123e4567-e89b-12d3-a456-426614174004",
  "mediaUrl": "https://example.com/media.png",
  "loyaltyUserAllotmentCsvUrl": "https://example.com/loyalty-user-allotment.csv",
  "maxAmountPerInterval": 100,
  "maxAmountInterval": "daily",
  "shopifyStoreUrl": "https://example.com",
  "externalIntegrationId": "123e4567-e89b-12d3-a456-426614174005",
  "duplicatedFromId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rewardLifetime": "permanent",
  "claimType": "auto"
}

Authorizations

​
X-API-KEY
string
header
required

Body

application/json

Body

Schema for creating a new loyalty rule with detailed validations

​
organizationId
string<uuid>
required

Unique identifier for the organization creating the rule

Example:

"123e4567-e89b-12d3-a456-426614174001"

​
websiteId
string<uuid>
required

Unique identifier for the associated website

Example:

"123e4567-e89b-12d3-a456-426614174002"

​
name
string
required

Name of the loyalty rule

Minimum length: 1
Example:

"Referral Bonus Rule"

​
type
enum<string>
required

Type of loyalty rule being created

Available options:
Bonus,
BoughtOn,
BoughtWithRoyalties,
DiscordMessages,
Listing,
Lodging,
MintOn,
PoapClaim,
SnagSocialsConnected,
SnapshotFullset,
SnapshotHold,
SoldOn,
SoldWithRoyalties,
TokenHold,
TwitterBio,
TwitterHashTagPost,
Retweet,
check_in,
code_entry,
connect_wallet,
connected_discord,
connected_email,
connected_epic,
connected_steam,
connected_telegram,
connected_twitter,
create_partner_account,
discord_member,
drip_x_follow,
drip_x_new_tweet,
drip_x_text_in_bio,
drip_x_text_in_comment,
drip_x_text_in_name,
drip_x_tweet,
external_rule,
link_click,
manual_upload,
profile_completed,
referred_user,
smart_contract_event,
snapshot_governance,
telegram_join,
telegram_messages,
text_input,
token_hold_erc20,
tweet_liked_by_project,
twitter_comment,
twitter_follow,
twitter_followers,
twitter_like,
twitter_post_hashtag,
quiz,
poll,
steam_wishlist,
liquidity_uniswap_v2,
liquidity_uniswap_v3,
points_airdrop,
youtube_subscribers,
youtube_comment,
shopify_spend,
swap,
tiktok_post,
post_impressions,
discord_join,
connected_youtube,
connected_tiktok
Example:

"Bonus"

​
frequency
enum<string>
required

Execution frequency of the loyalty rule

Available options:
none,
once,
daily,
weekly,
monthly,
immediately
Example:

"daily"

​
startTime
string<date-time> | null
required

When the rule becomes active

Example:

"2024-01-01T00:00:00Z"

​
endTime
string<date-time> | null
required

When the rule becomes inactive

Example:

"2024-12-31T23:59:00Z"

​
effectiveStartTime
required

The effective start time of the rule

Example:

"2024-01-01T00:00:00Z"

​
effectiveEndTime
required

The effective end time of the rule

Example:

"2024-12-31T23:59:00Z"

​
amount
any
required

Reward amount associated with the rule

​
metadata
object
required

Additional metadata for the loyalty rule

​
loyaltyCurrencyId
string<uuid>
required

Unique identifier for the loyalty currency

Example:

"456e1234-e89b-12d3-a456-426614174003"

​
backgroundAssetUrl
string

URL of the background asset to be displayed

Example:

"https://example.com/background.png"

​
description
string

Optional detailed description of the rule

Example:

"A loyalty rule rewarding users for referrals."

​
network
enum<string>
default:mainnet

Blockchain network where the rule will apply

Available options:
abstract,
abstractTestnet,
apechain,
arbitrum,
avalanche,
avalancheFuji,
base,
baseSepolia,
berachain,
berachainArtio,
berachainBepolia,
binance,
bscTestnet,
campTestnet,
fantom,
fantomTestnet,
flowMainnet,
mainnet,
nexusTestnet,
optimism,
polygon,
polygon_mumbai,
skaleNebula,
skaleEuropa,
skaleCalypso,
solana,
sophon,
sophonTestnet,
sui,
superseed,
superseedSepolia,
vanar,
xai,
zksync,
coti,
cotiTestnet,
morph,
morphTestnet,
morphHolesky,
ultra,
ultraTestnet,
nitrograph,
sepolia,
optimism_sepolia,
arbitrumSepolia,
goerli,
optimism_goerli,
arbitrumGoerli,
basecamp,
somnia,
flow_cadence
Example:

"mainnet"

​
interval
enum<string> | null

Interval between rule executions

Available options:
daily,
weekly,
monthly,
once,
custom,
every_message,
unlimited
Example:

"weekly"

​
customRewardsCsvUrl
string<uri> | null

URL for uploading custom rewards via CSV

Example:

"https://example.com/rewards.csv"

​
customRewardsApiUrl
string<uri> | null

URL for fetching custom rewards

Example:

"https://api.example.com/rewards"

​
subscriptionId
string | null

Optional subscription id for the rule

Example:

"sub12345"

​
collectionAddress
string

Blockchain address of the associated collection

Example:

"0x1234567890abcdef1234567890abcdef12345678"

​
collections
Collections · object[] | null

List of associated collections

​
hideInUi
boolean
default:false

Whether to hide this rule in the user interface

Example:

false

​
showBeforeStart
boolean
default:false

Whether to show this rule before the start time

Example:

false

​
isRequired
boolean
default:false

Whether this rule is mandatory

Example:

true

​
oauthCredentialsId
string<uuid> | null

OAuth credentials associated with the rule

Example:

"123e4567-e89b-12d3-a456-426614174003"

​
loyaltyRuleGroupId

Unique identifier for the loyalty rule group

Available options:
no-section
Example:

"123e4567-e89b-12d3-a456-426614174004"

​
rewardType
enum<string>
default:points

Type of reward issued by the rule

Available options:
points,
multiplier,
badge
Example:

"points"

​
loyaltyBadgeId
string<uuid> | null

Unique identifier for the loyalty badge

Example:

"123e4567-e89b-12d3-a456-426614174004"

​
mediaUrl
string | null

URL of the media to be displayed

Example:

"https://example.com/media.png"

​
loyaltyUserAllotmentCsvUrl
string<uri>

URL for uploading loyalty user allotment via CSV

Example:

"https://example.com/loyalty-user-allotment.csv"

​
maxAmountPerInterval
number | null

The maximum amount of points a user can earn per interval. Available for the smart contract and external rules.

Example:

100

​
maxAmountInterval
enum<string> | null

The interval for the max amount. Available for the smart contract and external rules.

Available options:
daily,
weekly,
monthly,
lifetime
Example:

"daily"

​
shopifyStoreUrl
string | null

URL of the Shopify store

Example:

"https://example.com"

​
externalIntegrationId
string<uuid> | null

ID of the external integration

Example:

"123e4567-e89b-12d3-a456-426614174005"

​
duplicatedFromId
string<uuid> | null
​
rewardLifetime
enum<string> | null

The lifetime of the reward

Available options:
permanent,
dynamic
Example:

"permanent"

​
claimType
enum<string> | null

The type of claim for the reward

Available options:
manual,
auto
Example:

"auto"

Response

200

Schema for creating a new loyalty rule with detailed validations

​
id
string<uuid>
required
​
organizationId
string<uuid>
required

Unique identifier for the organization creating the rule

Example:

"123e4567-e89b-12d3-a456-426614174001"

​
websiteId
string<uuid>
required

Unique identifier for the associated website

Example:

"123e4567-e89b-12d3-a456-426614174002"

​
name
string
required

Name of the loyalty rule

Minimum length: 1
Example:

"Referral Bonus Rule"

​
type
enum<string>
required

Type of loyalty rule being created

Available options:
Bonus,
BoughtOn,
BoughtWithRoyalties,
DiscordMessages,
Listing,
Lodging,
MintOn,
PoapClaim,
SnagSocialsConnected,
SnapshotFullset,
SnapshotHold,
SoldOn,
SoldWithRoyalties,
TokenHold,
TwitterBio,
TwitterHashTagPost,
Retweet,
check_in,
code_entry,
connect_wallet,
connected_discord,
connected_email,
connected_epic,
connected_steam,
connected_telegram,
connected_twitter,
create_partner_account,
discord_member,
drip_x_follow,
drip_x_new_tweet,
drip_x_text_in_bio,
drip_x_text_in_comment,
drip_x_text_in_name,
drip_x_tweet,
external_rule,
link_click,
manual_upload,
profile_completed,
referred_user,
smart_contract_event,
snapshot_governance,
telegram_join,
telegram_messages,
text_input,
token_hold_erc20,
tweet_liked_by_project,
twitter_comment,
twitter_follow,
twitter_followers,
twitter_like,
twitter_post_hashtag,
quiz,
poll,
steam_wishlist,
liquidity_uniswap_v2,
liquidity_uniswap_v3,
points_airdrop,
youtube_subscribers,
youtube_comment,
shopify_spend,
swap,
tiktok_post,
post_impressions,
discord_join,
connected_youtube,
connected_tiktok
Example:

"Bonus"

​
frequency
enum<string>
required

Execution frequency of the loyalty rule

Available options:
none,
once,
daily,
weekly,
monthly,
immediately
Example:

"daily"

​
startTime
string<date-time> | null
required

When the rule becomes active

Example:

"2024-01-01T00:00:00Z"

​
endTime
string<date-time> | null
required

When the rule becomes inactive

Example:

"2024-12-31T23:59:00Z"

​
effectiveStartTime
required

The effective start time of the rule

Example:

"2024-01-01T00:00:00Z"

​
effectiveEndTime
required

The effective end time of the rule

Example:

"2024-12-31T23:59:00Z"

​
amount
any
required

Reward amount associated with the rule

​
metadata
object
required

Additional metadata for the loyalty rule

​
loyaltyCurrencyId
string<uuid>
required

Unique identifier for the loyalty currency

Example:

"456e1234-e89b-12d3-a456-426614174003"

​
backgroundAssetUrl
string

URL of the background asset to be displayed

Example:

"https://example.com/background.png"

​
description
string

Optional detailed description of the rule

Example:

"A loyalty rule rewarding users for referrals."

​
network
enum<string>
default:mainnet

Blockchain network where the rule will apply

Available options:
abstract,
abstractTestnet,
apechain,
arbitrum,
avalanche,
avalancheFuji,
base,
baseSepolia,
berachain,
berachainArtio,
berachainBepolia,
binance,
bscTestnet,
campTestnet,
fantom,
fantomTestnet,
flowMainnet,
mainnet,
nexusTestnet,
optimism,
polygon,
polygon_mumbai,
skaleNebula,
skaleEuropa,
skaleCalypso,
solana,
sophon,
sophonTestnet,
sui,
superseed,
superseedSepolia,
vanar,
xai,
zksync,
coti,
cotiTestnet,
morph,
morphTestnet,
morphHolesky,
ultra,
ultraTestnet,
nitrograph,
sepolia,
optimism_sepolia,
arbitrumSepolia,
goerli,
optimism_goerli,
arbitrumGoerli,
basecamp,
somnia,
flow_cadence
Example:

"mainnet"

​
interval
enum<string> | null

Interval between rule executions

Available options:
daily,
weekly,
monthly,
once,
custom,
every_message,
unlimited
Example:

"weekly"

​
customRewardsCsvUrl
string<uri> | null

URL for uploading custom rewards via CSV

Example:

"https://example.com/rewards.csv"

​
customRewardsApiUrl
string<uri> | null

URL for fetching custom rewards

Example:

"https://api.example.com/rewards"

​
subscriptionId
string | null

Optional subscription id for the rule

Example:

"sub12345"

​
collectionAddress
string

Blockchain address of the associated collection

Example:

"0x1234567890abcdef1234567890abcdef12345678"

​
collections
Collections · object[] | null

List of associated collections

​
hideInUi
boolean
default:false

Whether to hide this rule in the user interface

Example:

false

​
showBeforeStart
boolean
default:false

Whether to show this rule before the start time

Example:

false

​
isRequired
boolean
default:false

Whether this rule is mandatory

Example:

true

​
oauthCredentialsId
string<uuid> | null

OAuth credentials associated with the rule

Example:

"123e4567-e89b-12d3-a456-426614174003"

​
loyaltyRuleGroupId

Unique identifier for the loyalty rule group

Available options:
no-section
Example:

"123e4567-e89b-12d3-a456-426614174004"

​
rewardType
enum<string>
default:points

Type of reward issued by the rule

Available options:
points,
multiplier,
badge
Example:

"points"

​
loyaltyBadgeId
string<uuid> | null

Unique identifier for the loyalty badge

Example:

"123e4567-e89b-12d3-a456-426614174004"

​
mediaUrl
string | null

URL of the media to be displayed

Example:

"https://example.com/media.png"

​
loyaltyUserAllotmentCsvUrl
string<uri>

URL for uploading loyalty user allotment via CSV

Example:

"https://example.com/loyalty-user-allotment.csv"

​
maxAmountPerInterval
number | null

The maximum amount of points a user can earn per interval. Available for the smart contract and external rules.

Example:

100

​
maxAmountInterval
enum<string> | null

The interval for the max amount. Available for the smart contract and external rules.

Available options:
daily,
weekly,
monthly,
lifetime
Example:

"daily"

​
shopifyStoreUrl
string | null

URL of the Shopify store

Example:

"https://example.com"

​
externalIntegrationId
string<uuid> | null

ID of the external integration

Example:

"123e4567-e89b-12d3-a456-426614174005"

​
duplicatedFromId
string<uuid> | null
​
rewardLifetime
enum<string> | null

The lifetime of the reward

Available options:
permanent,
dynamic
Example:

"permanent"

​
claimType
enum<string> | null

The type of claim for the reward

Available options:
manual,
auto
Example:

"auto"

⌘I