Skip to main content
POST
Create Loyalty Rule

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 string length: 1
Example:

"Referral Bonus Rule"

type
enum<string>
required

Type of loyalty rule being created

Available options:
Bonus,
BoughtOn,
BoughtWithRoyalties,
DiscordMessages,
Listing,
Lodging,
PoapClaim,
SnagSocialsConnected,
SnapshotFullset,
SnapshotHold,
SoldWithRoyalties,
TwitterBio,
TwitterHashTagPost,
MintOn,
SoldOn,
TokenHold,
Retweet,
check_in,
code_entry,
connect_wallet,
connected_discord,
connected_email,
connected_epic,
connected_github,
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,
stratus_function,
connected_tiktok,
tiktok_follow,
github_repo_star,
github_repo_fork,
github_repo_collaborator,
github_merge_PR,
discord_role_grant,
connected_reddit,
reddit_comment,
robinhood_token_hold,
connected_instagram,
instagram_post,
instagram_follow,
connected_phone,
dapps_by_gas_spent,
dapps_by_active_users,
dapps_by_new_users,
dapps_by_transaction_count,
dapps_by_user_retention
Example:

"TokenHold"

frequency
enum<string>
required

Execution frequency of the loyalty rule

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

"daily"

interval
enum<string>
required

Interval between rule executions

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

"weekly"

startTime
string<date-time>
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 | null
required

Reward amount associated with the rule

Example:

"10.5"

metadata
Metadata · object
required

Additional metadata for the loyalty rule

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,
nexus,
nexusTestnet,
optimism,
polygon,
polygon_mumbai,
skaleNebula,
skaleEuropa,
skaleCalypso,
solana,
sophon,
sophonTestnet,
sui,
superseed,
superseedSepolia,
vanar,
xai,
zksync,
coti,
cotiTestnet,
dogeosTestnet,
morph,
morphTestnet,
morphHolesky,
ultra,
ultraTestnet,
nitrograph,
sepolia,
optimism_sepolia,
arbitrumSepolia,
goerli,
optimism_goerli,
arbitrumGoerli,
basecamp,
somnia,
zkverify,
polkadot,
kusama,
horizen,
horizenTestnet,
robinhoodChain,
robinhoodChainTestnet,
flow_cadence
Example:

"mainnet"

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 stratus subscription id for the rule

Example:

"sub12345"

functionId
string | null

Optional stratus function id for the rule

Example:

"func12345"

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

trackProgress
boolean

Flag indicating if the progress is tracked. If enabled, the rule can only be completed once the progress is 100%.

Example:

true

progressType
enum<string> | null

How tracked progress is interpreted. "percentage" counts 0-100 and is shown as a percentage. "counter" counts up to the highest reward range end and is shown as a raw count.

Available options:
counter,
percentage
Example:

"percentage"

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"

loyaltyCurrencyId
string<uuid>

Unique identifier for the loyalty currency. Optional when rewardType is token and tokenReward is provided; backend will find or create the currency from the selected contract.

Example:

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

tokenReward
Token Reward · object

When rewardType is token, provide relayer and either an ERC-20 contract or isNative=true to find or create loyalty currency and onchain token.

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,
token
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"

contractIds
string[] | null

The IDs of the contracts

Example:
dappDeployedWithin
enum<string> | null

Filter dApps by deployment age before ranking.

Available options:
daily,
weekly,
monthly
Example:

"daily"

dappDataWindow
enum<string> | null

Reward based on data usage within the last day, week, or month. Leave it empty for all time usage.

Available options:
daily,
weekly,
monthly
Example:

"daily"

isDappRule
boolean

Routes rule rewards to the dApp owner address (for substitution-type rules: external_rule, smart_contract_event, stratus_function) or marks the rule as a dApp-attribution rule (for the dapps_by_* family). Defaults to true at the API for the dapps_by_* family when omitted, false otherwise. Immutable after creation.

Example:

false

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 string length: 1
Example:

"Referral Bonus Rule"

type
enum<string>
required

Type of loyalty rule being created

Available options:
Bonus,
BoughtOn,
BoughtWithRoyalties,
DiscordMessages,
Listing,
Lodging,
PoapClaim,
SnagSocialsConnected,
SnapshotFullset,
SnapshotHold,
SoldWithRoyalties,
TwitterBio,
TwitterHashTagPost,
MintOn,
SoldOn,
TokenHold,
Retweet,
check_in,
code_entry,
connect_wallet,
connected_discord,
connected_email,
connected_epic,
connected_github,
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,
stratus_function,
connected_tiktok,
tiktok_follow,
github_repo_star,
github_repo_fork,
github_repo_collaborator,
github_merge_PR,
discord_role_grant,
connected_reddit,
reddit_comment,
robinhood_token_hold,
connected_instagram,
instagram_post,
instagram_follow,
connected_phone,
dapps_by_gas_spent,
dapps_by_active_users,
dapps_by_new_users,
dapps_by_transaction_count,
dapps_by_user_retention
Example:

"TokenHold"

frequency
enum<string>
required

Execution frequency of the loyalty rule

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

"daily"

interval
enum<string>
required

Interval between rule executions

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

"weekly"

startTime
string<date-time>
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 | null
required

Reward amount associated with the rule

Example:

"10.5"

metadata
Metadata · object
required

Additional metadata for the loyalty rule

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,
nexus,
nexusTestnet,
optimism,
polygon,
polygon_mumbai,
skaleNebula,
skaleEuropa,
skaleCalypso,
solana,
sophon,
sophonTestnet,
sui,
superseed,
superseedSepolia,
vanar,
xai,
zksync,
coti,
cotiTestnet,
dogeosTestnet,
morph,
morphTestnet,
morphHolesky,
ultra,
ultraTestnet,
nitrograph,
sepolia,
optimism_sepolia,
arbitrumSepolia,
goerli,
optimism_goerli,
arbitrumGoerli,
basecamp,
somnia,
zkverify,
polkadot,
kusama,
horizen,
horizenTestnet,
robinhoodChain,
robinhoodChainTestnet,
flow_cadence
Example:

"mainnet"

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 stratus subscription id for the rule

Example:

"sub12345"

functionId
string | null

Optional stratus function id for the rule

Example:

"func12345"

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

trackProgress
boolean

Flag indicating if the progress is tracked. If enabled, the rule can only be completed once the progress is 100%.

Example:

true

progressType
enum<string> | null

How tracked progress is interpreted. "percentage" counts 0-100 and is shown as a percentage. "counter" counts up to the highest reward range end and is shown as a raw count.

Available options:
counter,
percentage
Example:

"percentage"

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"

loyaltyCurrencyId
string<uuid>

Unique identifier for the loyalty currency. Optional when rewardType is token and tokenReward is provided; backend will find or create the currency from the selected contract.

Example:

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

tokenReward
Token Reward · object

When rewardType is token, provide relayer and either an ERC-20 contract or isNative=true to find or create loyalty currency and onchain token.

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,
token
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"

contractIds
string[] | null

The IDs of the contracts

Example:
dappDeployedWithin
enum<string> | null

Filter dApps by deployment age before ranking.

Available options:
daily,
weekly,
monthly
Example:

"daily"

dappDataWindow
enum<string> | null

Reward based on data usage within the last day, week, or month. Leave it empty for all time usage.

Available options:
daily,
weekly,
monthly
Example:

"daily"

isDappRule
boolean

Routes rule rewards to the dApp owner address (for substitution-type rules: external_rule, smart_contract_event, stratus_function) or marks the rule as a dApp-attribution rule (for the dapps_by_* family). Defaults to true at the API for the dapps_by_* family when omitted, false otherwise. Immutable after creation.

Example:

false