Snag Solutions

Authentication Type: API Key
Description: Access loyalty transaction history and badges from Snag Solutions API for comprehensive loyalty program data management.

Loyalty

Operations for accessing loyalty program data including transactions and badges.

Get Transaction Entries

Retrieve loyalty transaction history for a wallet address. Returns transaction details including amounts, rules, and metadata.

Operation Type: Query (Read)

Parameters:

• organizationId string (nullable): Organization ID to filter by
• websiteId string (nullable): Website ID to filter by
• walletAddress string (required): Wallet address to get transaction history for
• startingAfter string (nullable): Pagination cursor to start after a specific resource ID
• limit number (nullable): Maximum number of records to return (max 100)
• userId string (nullable): User ID to filter by
• sortBy string (nullable): Field to sort the results by (createdAt, updatedAt, loyaltyAccountLockVersion)
• sortDir string (nullable): Direction to sort the results by (asc, desc)
• createdAtStart string (nullable): Start date to filter by (inclusive, greater than or equal to)
• createdAtEnd string (nullable): End date to filter by (exclusive, less than)
• loyaltyRuleGroupId string (nullable): UUID of the rule group to filter by
• loyaltyCurrencyId string (nullable): UUID of the loyalty currency IDs to filter by

Returns:

• data array of objects: Array of transaction entries
  • id string: Transaction entry ID
  • loyaltyAccountId string: Loyalty account ID
  • loyaltyTransactionId string: Loyalty transaction ID
  • loyaltyCurrencyId string: Loyalty currency ID
  • amount string: Transaction amount
  • direction string: Transaction direction (credit/debit)
  • metadata object: Transaction metadata
  • loyaltyAccountStartAmount string: Account balance before transaction
  • loyaltyAccountEndAmount string: Account balance after transaction
  • createdAt string: Creation timestamp
  • updatedAt string: Update timestamp
  • loyaltyAccount object: Loyalty account details
    • id string: Loyalty account ID
    • user object: User information
      • id string: User ID
      • walletAddress string: Wallet address
  • loyaltyTransaction object: Loyalty transaction details
    • id string: Transaction ID
    • description string: Transaction description
    • type string: Transaction type
    • metadata object: Transaction metadata
    • loyaltyRule object (nullable): Loyalty rule details
      • id string: Loyalty rule ID
      • name string: Loyalty rule name
      • description string: Loyalty rule description
      • type string: Loyalty rule type
• hasNextPage boolean: Whether there are more pages available

Example Usage:

{
  "organizationId": "org_123",
  "websiteId": "web_456",
  "walletAddress": "0x1234567890abcdef",
  "startingAfter": null,
  "limit": 50,
  "sortBy": "createdAt",
  "sortDir": "desc",
  "createdAtStart": "2024-12-01T00:00:00Z",
  "createdAtEnd": "2024-12-31T23:59:59Z"
}

Get Badges

Fetch badges earned by users. Can filter by wallet address, user ID, or specific badge IDs to get badge information and user progress.

Operation Type: Query (Read)

Parameters:

• organizationId string (nullable): Organization ID to filter by
• websiteId string (nullable): Website ID to filter by
• walletAddress string (nullable): Wallet address to filter badges for
• userId string (nullable): User ID to filter badges for
• badgeIds string (nullable): Comma-separated badge IDs to fetch
• userGroupId string (nullable): User group ID to filter by
• userGroupExternalIdentifier string (nullable): External identifier of the user group
• startingAfter string (nullable): Badge ID to start after for pagination
• limit number (nullable): Number of badges to fetch (max 1000)
• includeDeleted boolean (nullable): Include deleted badges in the response

Returns:

• data array of objects: Array of badges
  • id string: Badge ID
  • name string: Badge name
  • description string (nullable): Badge description
  • imageUrl string (nullable): Badge image URL
  • loyaltyConditions array of objects: Badge loyalty conditions
    • id string: Condition ID
    • type string: Condition type
    • description string (nullable): Condition description
    • amount string (nullable): Condition amount
    • repeatCount number (nullable): Repeat count
    • requiredCount number (nullable): Required count
    • loyaltyRuleGroupId string (nullable): Loyalty rule group ID
    • loyaltyCurrencyId string (nullable): Loyalty currency ID
  • loyaltyBadgeUsers array of objects: Badge users
    • id string: Badge user ID
    • userId string: User ID
    • user object: User information
      • id string: User ID
      • walletAddress string: Wallet address
    • status string: Badge status
    • progress array: Badge progress
    • createdAt string: Creation timestamp
    • updatedAt string: Update timestamp
• hasNextPage boolean: Whether there are more pages available

Example Usage:

{
  "organizationId": "org_123",
  "websiteId": "web_456",
  "walletAddress": "0x1234567890abcdef",
  "userId": null,
  "badgeIds": "badge_001,badge_002",
  "startingAfter": null,
  "limit": 100,
  "includeDeleted": false
}

Common Use Cases

Transaction Analysis:

• Track loyalty point earnings and spending for individual users
• Analyze transaction patterns by date ranges and rule groups
• Monitor account balances and transaction history
• Generate reports on loyalty program engagement

Badge Management:

• Monitor badge achievement progress for users
• Track badge completion rates and user engagement
• Filter badges by specific criteria for targeted analysis
• Manage badge visibility and deletion status

User Insights:

• Analyze user behavior through transaction and badge data
• Identify high-value users based on loyalty activity
• Track user progression through loyalty program tiers
• Generate user-specific loyalty reports and insights