Skip to main content
Quest chaining lets you combine multiple rules into a guided, multi-step experience. Users must complete prerequisite steps in sequence before they can complete and claim the final quest’s rewards. This is ideal for onboarding journeys, progressive learning paths, campaigns, or complex eligibility workflows.

​
How quest chaining works

  • Chain: A named container that links one “final” rule to one or more prerequisite conditions.
  • Final rule: The quest users ultimately complete (and usually get the reward for). Represented by a loyaltyRuleId.
  • Conditions: One or more requirements that must be fulfilled before the final rule can be completed. Conditions can reference other rules, counts, or other supported condition types.
  • Status: You can fetch per-user (or per user group) progress across the chain to show locked/unlocked steps and completion.
Quest chaining is a feature flag. Ensure your plan has Quest chaining enabled.

​
Enable the feature

You need the enableQuestChaining feature flag enabled on your billing website.
  • UI: Go to Admin → Billing → Plan features and enable “Quest chaining”.
  • API/Provisioning: Your website record should have enableQuestChaining = true.
If the feature is disabled, quest chain UI and APIs will be restricted.

​
Typical use cases

  • Onboarding series (e.g., connect wallet → join Discord → post on X → claim reward)
  • Education paths (e.g., watch video → pass quiz → mint badge)
  • Referral gating (e.g., referral reward releases only after the referee completes a quest)
  • Seasonal campaigns with progressive unlocks

​
Condition types

Quest chains support multiple condition types that define prerequisites for completing the final rule. You can mix and match different condition types within a single chain.

​
Rule completion

Requires a user to complete a specific rule/quest before the final rule can be unlocked. Configuration:
  • Select a single rule that must be completed
  • Optional: Set repeatCount to require the rule to be completed multiple times (e.g., complete 3 times)
Example: “Connect wallet” must be completed before unlocking “Join Discord”

​
Multiple rule completions

Requires users to complete multiple rules, with flexible minimum requirements. Configuration:
  • Select multiple rules (e.g., 5 different quests)
  • Set requiredCount to specify the minimum number that must be completed (e.g., complete at least 3 out of 5)
Example: Complete 3 out of 5 daily challenges to unlock the weekly bonus quest

​
Achieve points

Requires a user to reach a specific points threshold in their loyalty account balance. Configuration:
  • Set amount to the minimum points required
Example: Achieve 1,000 points before unlocking the VIP badge quest

​
Achieve badge

Requires a user to earn a specific badge before the final rule can be completed. Configuration:
  • Select a single badge that must be earned
Example: Earn the “Early Adopter” badge to unlock exclusive content quest

​
Achieve multiple badges

Requires users to earn multiple badges, with flexible minimum requirements. Configuration:
  • Select multiple badges (e.g., 5 different badges)
  • Set requiredCount to specify the minimum number that must be earned (e.g., earn at least 3 out of 5)
Example: Earn 3 out of 5 skill badges to unlock the “Master” certification quest
When using requiredCount for multiple rule completions or multiple badges, users can complete any combination of the selected items as long as the minimum count is met.

​
Create a quest chain (UI)

1

Open Loyalty → Quest Chaining

From the admin app, navigate to Loyalty → Quest Chaining and click “Add new chain”.
2

Name the chain and select the final rule

Pick the quest that users will ultimately complete and receive rewards for.
3

Add prerequisite conditions

Add one or more conditions. The most common is a Rule condition pointing to another quest that must be completed first.
4

Save

The chain becomes active immediately once saved. You can edit or delete it later.

​
List

curl -X GET 'https://admin.snagsolutions.io/api/loyalty/rule_chains?organizationId=ORG_ID&websiteId=WEB_ID&limit=10' \
  -H 'X-API-KEY: YOUR_API_KEY'

​
Fetch chain statuses

Get per-user or per user-group progress for a chain. 
curl -X GET 'https://admin.snagsolutions.io/api/loyalty/rule_chains/CHAIN_ID/statuses?organizationId=ORG_ID&websiteId=WEB_ID&userId=USER_ID' \
  -H 'X-API-KEY: YOUR_API_KEY'
You must provide either userGroupId or userId (single or array). Max 20 user IDs per request.

​
Reward behavior and locking

  • The final rule’s reward is typically locked until all prerequisite conditions are met.
  • If a rule is part of a chain, internal reward handlers will suppress rewards until the chain is complete for that user.

​
Referral-specific behavior

When you chain a referral rule to another quest, rewards for the referrer will only process after the referee completes the chained quest. This ensures referrals are only rewarded when the referee actually performs the intended action.
If quest chaining is enabled for a referral flow, rewards will not process until the chained quest is completed by the referred user, regardless of when the referral was recorded.

​
Best practices

  • Keep chains short and clear; show users exactly what’s required.
  • Use descriptive chain names (shown in admin and analytics).
  • Avoid circular dependencies; a rule should not indirectly depend on itself.
  • Pair chains with badges or multipliers for meaningful progression.
  • Monitor chain statuses to surface progress and nudge users.

​
Troubleshooting

  • Final reward not unlocking: Verify all prerequisite conditions are satisfied for the user and that the correct loyaltyRuleId is set on the chain.
  • Chain not visible: Ensure enableQuestChaining is true for the website and your API key has permissions for Rule Chains.
  • Statuses endpoint returns empty: Provide userId or userGroupId and check the API key/organization/website IDs.
  • Referral rewards not firing: Confirm the chained quest is completed by the referee and that the referral rule is configured correctly.