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

​
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.