📌 Purpose

As wallets are created, one or more loyalty accounts may be needed to track and manage points for schemes across a loyalty program. The Create Loyalty Account API enables creation of an account tied to a specific loyalty scheme. This recipe outlines how to prepare the API call to create a points account and subsequently credit it using the Points Credit API.

🖼 Recipe Overview

This recipe walks through the process of creating a points account and applying an initial balance. Once established, the account can be used to issue and redeem points as dictated by the loyalty scheme’s configuration. By completing this process, you will have:

An active points account within the wallet
An available balance of 12,500 points

📋 Prerequisites

Eagle Eye API access
Company unit's clientId & secret
3-level unit hierarchy with an active company
schemeId of an active loyalty scheme
walletId of a customer wallet

📤 Outputs

After completing this recipe, capture the following output:

Output Name	Purpose
accountId	Used to make account specific API calls, such as crediting points

📒 Steps

Step 1: Prepare the request to create a points account

1.1 Use status: ACTIVE and state: EARNBURN to ensure the account can be credited immediately
1.2 Start and end dates will be inherited from the scheme

Step 2: Call POST /wallet/{walletId}/scheme/{schemeId}/account

{
  "status": "ACTIVE",
  "state": "EARNBURN"
}

{
	"accountId": "4421285350",
	"walletId": "241868742",
	"campaignId": "101161638",
	"type": "POINTS",
	"clientType": "RETAILPOINTS",
	"status": "ACTIVE",
	"state": "EARNBURN",
	"dates": {
		"start": "2025-06-18T20:14:35+00:00",
		"end": "2038-01-19T03:14:07+00:00"
	},
	"meta": [],
	"dateCreated": "2025-06-18T20:14:35+00:00",
	"lastUpdated": "2025-06-18T20:14:35+00:00",
	"overrides": [],
	"balances": {
		"current": 0,
		"usable": 0,
		"locked": 0,
		"lifetime": 0,
		"lifetimeSpend": 0,
		"lifetimeSpendValue": 0,
		"pending": 0
	},
	"relationships": [],
	"mobileWallet": "https://sb.uk.mypass.is/a/4421285350/be7df2776913831"
}

Step 3: Prepare the request payload for the credit points call

3.1 Decide the number of points to apply. In this example, we are crediting 12,500 points
3.2 Use the points account accountId in the PATCH API call's URL for step 4

Step 4: Call PATCH /wallet/{walletId}/account/{accountId}/credit

{
  "balances": {
    "current": 12500
  }
}

{
	"accountTransactionId": "8708449935",
	"parentAccountTransactionId": "",
	"accountId": "4421285350",
	"account": {
		"accountId": "4421285350",
		"walletId": "241868742",
		"campaignId": "101161638",
		"type": "POINTS",
		"clientType": "RETAILPOINTS",
		"status": "ACTIVE",
		"state": "EARNBURN",
		"dates": {
			"start": "2025-06-18T20:14:35+00:00",
			"end": "2038-01-19T03:14:07+00:00"
		},
		"meta": [],
		"dateCreated": "2025-06-18T20:14:35+00:00",
		"lastUpdated": "2025-06-18T20:17:12+00:00",
		"overrides": [],
		"balances": {
			"current": 12500,
			"usable": 12500,
			"lifetime": 12500,
			"pending": 0,
			"locked": 0,
			"lifetimeSpend": 0,
			"lifetimeSpendValue": 0
		},
		"relationships": [],
		"mobileWallet": "https://sb.uk.mypass.is/a/4421285350/be7df2776913831"
	},
	"event": "CREDIT",
	"value": 12500,
	"source": 1,
	"balancesBefore": {
		"current": 0,
		"lifetime": 0
	},
	"balancesAfter": {
		"current": 12500,
		"lifetime": 0
	},
	"transactionDetails": [],
	"properties": [],
	"dateCreated": "2025-06-18T20:17:12+00:00",
	"lastUpdated": "2025-06-18T20:17:12+00:00"
}

✅ Business Readiness Checklist

Use these steps to validate the setup of your wallet and accounts:

Check GET Account to verify the points accounts were created and credited.

🔧 Troubleshooting Tips

Issue	Possible Cause & Resolution
Account not created	Confirm the schemeId is valid and the scheme is in an ACTIVE state using GET Scheme