📌 Purpose

A Public Reward Bank allows any eligible customer to exchange their loyalty points for rewards, such as coupons or discounts. This recipe walks through how to execute a points-to-reward exchange using the /services/wallet/{walletId}/transaction/exchange/pointsreward API. Once the reward bank is set up, any wallet with enough points can redeem available offers without needing pre-targeted enrollment.

🖼 Recipe Overview

This recipe explains how to retrieve available rewards in a public reward bank and then process a sample exchange. By the end, you’ll:

Confirm which rewards are available for exchange
Execute a live points redemption
See the result reflected as a coupon in the wallet

📋 Prerequisites

Access to Eagle Eye APIs
Company unit's clientId & secret
Active 3-level unit hierarchy (company → banners → stores)
Points loyalty scheme
A customer wallet with an active points account
A reward bank with at least one configured reward

📤 Outputs

After completing this recipe, capture the following output:

Output Name	Purpose
walletTransactionId	Unique reference for the wallet transaction used to locate a transaction
accountTransactionId	Used to reference the specific movement of points and coupon issue

📒 Steps

Step 1: Call GET /banks/pointsreward/{rewardBankId}/rewards

You will need the pointsRewardBankRewardId for the specific reward you want to exchange. Use this API to list available rewards and points cost associate to it.

{
	"total": 1,
	"orderBy": [
		{
			"name": "pointsRewardBankRewardId",
			"order": "ASC"
		}
	],
	"limit": 100,
	"offset": 0,
	"results": [
		{
			"pointsRewardBankRewardId": "186252",
			"pointsRewardBankId": "84592",
			"resourceType": "CAMPAIGN",
			"resourceId": "101161513",
			"threshold": 1000,
			"cost": 1000,
			"status": "ACTIVE",
			"dateCreated": "2025-06-18T16:39:39+00:00",
			"lastUpdated": "2025-06-18T16:39:39+00:00",
			"reasonCode": null
		}
	]
}

Note the pointsRewardBankRewardId and cost value for the reward you want to exchange. You’ll need both in the next step.

Step 2: Prepare the exchange request payload

To ensure the wallet has enough points to process the redemption and that the correct pointsRewardBankId is referenced. Confirm the wallet’s points account has a usable balance greater than or equal to the cost from Step 1.

2.1 Input the wallet's points accountId in the request, along with the pointsRewardBankId and the pointsRewardBankRewardId from step 1

Step 3: Call POST /services/wallet/{walletId}/transaction/exchange/pointsreward

{
    "accountId": "4458380924",
    "pointsRewardBankId": "84592",
    "pointsRewardBankRewardId": "186252"
}

{
	"walletTransactionId": "482354871",
	"parentWalletTransactionId": "0",
	"walletId": "242039084",
	"reference": "EXCHANGE_685962ed34b7c9.11492285",
	"transactionDateTime": "2025-06-23T14:21:33+00:00",
	"transactionDateTimeOffset": "+00:00",
	"identityId": null,
	"identity": null,
	"type": "EXCHANGE",
	"status": "SETTLED",
	"meta": null,
	"state": "ORIGINAL",
	"expiryDate": null,
	"accounts": [
		{
			"accountTransactionId": "8764825968",
			"parentAccountTransactionId": "",
			"accountId": "4458380924",
			"account": {
				"accountId": "4458380924",
				"walletId": "242039084",
				"campaignId": "101159001",
				"type": "POINTS",
				"clientType": "RETAILPOINTS",
				"status": "ACTIVE",
				"state": "EARNBURN",
				"dates": {
					"start": "2025-06-23T13:21:18+00:00",
					"end": "2038-01-19T03:14:07+00:00"
				},
				"meta": [],
				"dateCreated": "2025-06-23T13:21:18+00:00",
				"lastUpdated": "2025-06-23T14:21:33+00:00",
				"overrides": [],
				"balances": {
					"current": 2000,
					"usable": 2000,
					"lifetime": 5000,
					"pending": 0,
					"locked": 0,
					"lifetimeSpend": 0,
					"lifetimeSpendValue": 0
				},
				"relationships": [],
				"mobileWallet": "https://sb.uk.mypass.is/a/4458380924/82e0b1eb38bc520"
			},
			"event": "EXCHANGE",
			"value": 1000,
			"source": 1,
			"balancesBefore": {
				"current": 3000,
				"lifetime": 0
			},
			"balancesAfter": {
				"current": 2000,
				"lifetime": 0
			},
			"transactionDetails": {
				"pointsRewardBankId": 84592,
				"pointsRewardBankRewardId": 186252,
				"rewardBankLoyaltyPointsBankId": 84592
			},
			"properties": [],
			"dateCreated": "2025-06-23T14:21:33+00:00",
			"lastUpdated": "2025-06-23T14:21:33+00:00"
		},
		{
			"accountTransactionId": "8764825969",
			"parentAccountTransactionId": "8764825968",
			"accountId": "4458381241",
			"account": {
				"accountId": "4458381241",
				"walletId": "242039084",
				"campaignId": "101161513",
				"type": "ECOUPON",
				"clientType": "OFFER",
				"status": "ACTIVE",
				"state": "UNLOADED",
				"dates": {
					"start": "2025-06-23T14:21:33+00:00",
					"end": "2025-07-07T23:59:59+00:00"
				},
				"meta": [],
				"dateCreated": "2025-06-23T14:21:33+00:00",
				"lastUpdated": "2025-06-23T14:21:33+00:00",
				"overrides": [],
				"balances": {
					"available": 0,
					"refundable": 0
				},
				"relationships": {
					"LOYALTY_POINTS_REWARD_OF": {
						"POINTS": [
							{
								"accountId": "4458380924",
								"dateCreated": "2025-06-23T14:21:33+00:00"
							}
						]
					}
				},
				"mobileWallet": "https://sb.uk.mypass.is/a/4458381241/ab820f7d4e4261a"
			},
			"event": "CREATE",
			"value": 0,
			"source": 1,
			"balancesBefore": {
				"available": 0,
				"refundable": 0
			},
			"balancesAfter": {
				"available": 0,
				"refundable": 0
			},
			"transactionDetails": [],
			"properties": [],
			"dateCreated": "2025-06-23T14:21:33+00:00",
			"lastUpdated": "2025-06-23T14:21:33+00:00"
		}
	],
	"basket": {
		"contents": null,
		"summary": null,
		"payment": null
	},
	"channel": "api",
	"location": {
		"storeId": null,
		"storeParentId": null
	},
	"dateCreated": "2025-06-23T14:21:33+00:00",
	"lastUpdated": "2025-06-23T14:21:33+00:00"
}

✅ Business Readiness Checklist

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

Check GET wallet/{walletId}/account/{accountId} to verify the coupon account was created

🔧 Troubleshooting Tips

Issue	Possible Cause & Resolution
Coupon not created	Ensure the reward bank and the linked campaign are both active. Also check if the wallet already has a coupon from that reward and is hitting a redemption limit.
Insufficient points	Validate usable point balance in the wallet points account
400 error	Ensure all fields (accountId, pointsRewardBankId, pointsRewardBankRewardId) are correctly populated