Multi-wallet accounts

​

Overview

In some cases, for example if you have an existing application for your end users, you may implement an account concept which allows your user to link multiple wallets. While Snag treats each wallet as its own account, we allow for setting of a walletGroupIdentifier property in the user’s account metadata. This is used to aggregate points balances in the Snag Loyalty UI and allows for aggregate points spending as well as data fetching from the Snag API.

​

Creating linked wallets

The POST /api/users/metadatas endpoint allows you to attach metadata to a given account in our system, notably including the walletGroupIdentifier property. The goal of this is to set the same value for the various wallets you wish to group together (in subsequent API requests to this endpoint).

• The value you set for the walletGroupIdentifier is arbitrary but must be consistent across the wallets you are linking together. We recommend using an accountId from your existing system if this is applicable to your use case.

• Once the walletGroupIdentifier has been set for the wallets you are linking, points earning and spending will be aggregated across the linked wallets.

  • Points earning: given most rules identify a rewardable wallet, this means that points will be issued to the relevant wallet

  • Points spending: this is where the walletGroupIdentifier takes effect. Consider this example: “Wallet1 and Wallet2 are linked and have respective balances of 100 and 50 XP. The user is connected with one of these wallets and wishes to execute a purchase for 120 XP. This will result in a balance check across the linked wallets and then deducting points from both of the wallets (as the spend amount exceeds the balance of any of the individual wallet in the group), resulting in balances of 0 and 30 XP, respectively.”

​

Fetching linked wallets

The GET /api/loyalty/accounts endpoint allows you to fetch user data which will include the walletGroupIdentifier property (if it has been set). This value can then be used for fetching points accrual and spending data from the Snag API.

​

Using Snag API with linked wallets

The various loyalty API endpoints allow for querying by walletGroupIdentifier as opposed to querying by the individual wallet addresses.

• API responses will be arrays containing entries for each of the linked wallets

  • e.g. The GET /api/loyalty/accounts endpoint will return an array with n entries, where n is the number of wallets that are linked together for the given walletGroupIdentifier. Each of these will include the relevant wallet’s XP balance which can then be aggregated in your application code to replicate how the Snag Loyalty UI shows aggregate balances.