# Snag Solutions

> Access loyalty transaction history and badges from Snag Solutions API for comprehensive loyalty program data management.

Source: https://cotera.co/docs/reference/tools/individual-tools/snag-solutions

---

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

***

## Authentication

To authenticate, you'll need a Snag Solutions API key. Learn how to get one in the [Snag Solutions API documentation](https://docs.snagsolutions.io/api-reference/introduction).

***

## 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:**

```json
{
  "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:**

```json
{
  "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