External loyalty rules

​

What is an external loyalty rule?

You may wish to track user behaviour in contexts that Snag is unable to obtain a data source for (e.g. in a non-web/blockchain based game). For this and similar cases, Snag provides the concept of external rules.

An external rule is mostly the same as a standard loyalty rule and differs only in that it is created via API instead of the admin dashboard and it contains no built-in execution and evaluation logic. Instead, this is done application-side (e.g. in-game) and, when a rewardable action is identified, Snag’s POST /api/loyalty/rules/{id}/complete endpoint can be hit. This tells Snag that a given rule was completed by the given user(s) and issues the associated reward.

​

How to set up an external loyalty rule

External loyalty rules must be created via the Snag API. To create one, use the POST /api/loyalty/rules endpoint with the relevant fields configured for your rule.

​

Example Request

{
  "organizationId": "your-organization-id",
  "websiteId": "your-website-id",
  "name": "External Game Achievement Rule",
  "description": "Rewards users for completing a specific milestone in a non-blockchain game.",
  "type": "external_rule",
  "frequency": "none",
  "rewardType": "points",
  "amount": "100",
  "metadata": {
    "customRewardsApiUrl": "https://your-game-api.com/rules/external"
  },
  "loyaltyCurrencyId": "your-loyalty-currency-id"
}

• type must be set to external_rule.
• frequency must be set to none.

​

Example Response

{
  "id": "rule-id",
  "name": "External Game Achievement Rule",
  "type": "external_rule",
  "rewardType": "points",
  "amount": "100",
  "status": "active"
}

The id returned in the response will be used to complete the rule when a user performs the required action.

​

Evaluating external rules

Unlike built-in rules, the evaluation of external rules happens within your own system. This means you must track the user behavior (e.g., game milestones or external API interactions) and determine when a rule is completed.

Once a rewardable action is identified, you can programmatically notify Snag by completing the external rule using the API (see next step).

​

How to issue points for users who complete an external rule

To issue points for a user who completes an external rule, use the POST /api/loyalty/rules/{id}/complete endpoint. This endpoint informs Snag that the rule has been satisfied for a specific user and triggers the reward.

​

Example Request

{
  "userId": "user-id"
}

• userId is the ID of the user who completed the rule.
• note: the ruleId is baked into the request URL and so can be omitted from the object above (as per the example).

​

Example Response

{
  "message": "Rule completion submitted. Rewards will be issued shortly."
}

Once the request is processed, Snag will issue the reward to the user based on the rule’s configuration.

​

Summary Workflow

1. Create the Rule: Use POST /api/loyalty/rules to do this.
2. Track Behavior: Use your application to monitor user actions that meet the rule’s criteria.
3. Complete the Rule: When a user completes the action, use POST /api/loyalty/rules/{id}/complete to notify Snag and issue the reward.