Brand, Banner and Store with Tiers Recipe
📌 Purpose
Setting up your retailer brand, banners, and stores is the first step in launching your loyalty program. This recipe guides you through creating your brand structure within the Eagle Eye platform, including your main brand, associated banners (such as store groups or franchises), and individual stores. This setup ensures your loyalty campaigns and customer rewards are linked to the correct store locations where customers shop and redeem offers. See the Create and Configure Tenant API reference for additional options that can be configured against companies.
🖼 Recipe Overview
In this recipe, you will set up your retailer brand (called a company unit), your banners (store groups or brands), and individual stores. This three-level structure is essential for creating loyalty schemes and campaigns. By the end, your brand will have a complete operational hierarchy ready to support points earning, offer redemption, tier enablement, and campaign targeting across all store locations.
📋 Prerequisites
Ensure you have:
- Access to Eagle Eye APIs
- Names for your retailer brand, banners, and stores
- Unique alphanumeric identifiers for each (no dashes allowed)
📤 Outputs
As you complete each step, note these outputs for future API calls and program validation:
| Output Name | Purpose |
|---|---|
| unitId | Identifies each brand, banner, and store you create |
| incomingIdentifier | The system name used in API calls for the brand, banner or store created |
| clientId and secret | Credentials for your parent company, used to create banners and stores |
📒 Steps
Step 1: Create Your Retailer Brand
Start by creating your main retailer brand in the platform. This is your top-level account that will own all banners, stores, and loyalty activities.
- 1.1 Choose a name for your brand
- 1.2 Select a unique alphanumeric identifier (no dashes) as incomingIdentifier
Only alphanumeric characters should be used for the incomingIdentifier. Do not use dashes (-).
- 1.3 Recommended configurations:
- POS Connect Mode: CUSTOMERWINS (ensures customer transactions take priority)
- Wallet Config Mode: CONSUMER (enables wallet API functionality)
Step 2: Call POST /services/units
Send the setup request to create your brand in the platform.
- 2.1 Use the POST /services/units endpoint
- 2.2 Save the clientId and secret returned, as these credentials are needed to create banners and stores under your brand
{
"name": "Fabulous Inc",
"incomingIdentifier": "fabulousinc",
"options": {
"posConnect": {
"mode": "CUSTOMERWINS"
},
"walletConfig": {
"mode": [
"CONSUMER"
]
},
"tiers": {
"enabled": true,
"mode": "INDIVIDUAL"
}
}
}{
"id": "171660",
"name": "Fabulous Inc",
"safeName": "fabulousinc",
"type": "COMPANY",
"status": "ACTIVE",
"reference": "0000171660",
"tags": [],
"incomingIdentifier": "fabulousinc",
"timezones": {
"default": "UTC"
},
"posConnect": {
"wallet": {
"events": {
"REFUND": [
"POSCONNECT.WALLET.REFUND"
],
"SETTLE": [
"POSCONNECT.WALLET.SETTLE"
],
"SPEND": [
"POSCONNECT.WALLET.SPEND"
],
"FULFIL": [
"POSCONNECT.WALLET.FULFIL"
],
"VOID": [
"POSCONNECT.WALLET.SPEND.VOID"
],
"PRODUCTEXCHANGE": [
"POSCONNECT.WALLET.PRODUCTEXCHANGE"
]
},
"fulfil": {
"enabled": true,
"filters": {
"accounts": {
"default": {
"status": [
"ACTIVE",
"LOCKED",
"EXPIRED",
"INACTIVE"
],
"accountType": [
"COUPON_ECOUPON",
"STORED_VALUE_VOUCHER",
"STORED_VALUE_DEBIT",
"STORED_VALUE_PLASTIC",
"LOYALTY_POINTS",
"COUPON_CONTINUITY",
"COUPON_STAMP_CARD",
"COUPON_MULTI_PROMOTION_COUPON",
"COUPON_QUEST"
],
"campaignsStatus": [
"ACTIVE",
"SUSPENDED",
"READY",
"EXPIRED"
]
}
}
},
"originalWalletTransaction": {
"additionalPayloadValues": {
"default": {
"finalise": {
"status": "SETTLED"
},
"fulfil": {
"status": "FULFILLING"
}
}
}
},
"walletTransaction": {
"additionalPayloadValues": {
"default": {
"status": "FULFILLED",
"type": "FULFIL"
}
}
}
},
"open": {
"filters": {
"accounts": {
"default": {
"state": [
"LOADED",
"EARNONLY",
"EARNBURN",
"HIDDEN"
],
"status": [
"ACTIVE",
"LOCKED"
],
"accountType": [
"COUPON_ECOUPON",
"LOYALTY_POINTS",
"COUPON_CONTINUITY",
"COUPON_STAMP_CARD",
"COUPON_MULTI_PROMOTION_COUPON",
"COUPON_QUEST"
],
"campaignsStatus": [
"READY",
"ACTIVE",
"EXPIRED",
"SUSPENDED"
]
}
}
},
"walletTransaction": {
"createAlwaysRequired": false,
"additionalPayloadValues": {
"default": {
"type": "SETTLE"
}
}
},
"options": {
"unusedAccounts": {
"enabled": true
},
"includeQualifyingOpenOffersInAccounts": true,
"disablePointsLocking": true,
"basketAnalysis": {
"campaign": {
"FREE_PRODUCTS": {
"ordering": {
"allFree": {
"key": "itemUnitCost",
"ascending": true
}
}
},
"FIXED_PERCENTAGE_OFF_PRODUCTS": {
"ordering": {
"percentageAmount": {
"key": "itemUnitCost",
"ascending": true
}
}
},
"FIXED_POINTS_PRODUCTS": {
"attachToMatchingProducts": true
},
"VARIABLE_AMOUNT_OFF_PRODUCTS": {
"ordering": {
"allFree": {
"key": "itemUnitCost",
"ascending": true
},
"percentageAmount": {
"key": "itemUnitCost",
"ascending": true
},
"finalAmount": {
"key": "itemUnitCost",
"ascending": true
}
}
}
}
}
}
},
"options": {
"basketAdjustment": {
"associateBasketDiscountToQualifyingProducts": true
},
"includeContributionResults": {
"active": true
},
"includePlayOrderPositions": {
"active": true
},
"includeQualifiesResults": {
"active": true
},
"ordering": {
"MEAL_DEAL": {
"direction": "asc",
"key": "itemUnitCost"
}
}
},
"permissionEngine": {
"error": [
{
"type": "identity",
"config": {
"attribute": "status",
"default": [],
"result": {
"SUSPENDED": false,
"STOLEN": false,
"INACTIVE": false
}
}
}
],
"spend": [
{
"config": {
"attribute": "state",
"default": [],
"result": {
"EARNONLY": false
}
},
"type": "account"
}
]
},
"productExchange": {
"filters": {
"accounts": {
"default": {
"status": [
"ACTIVE",
"USED",
"LOCKED",
"EXPIRED"
],
"accountType": [
"COUPON_ECOUPON",
"STORED_VALUE_VOUCHER",
"STORED_VALUE_DEBIT",
"STORED_VALUE_PLASTIC",
"LOYALTY_POINTS",
"COUPON_CONTINUITY",
"COUPON_STAMP_CARD",
"COUPON_MULTI_PROMOTION_COUPON",
"COUPON_QUEST"
],
"campaignsStatus": [
"ACTIVE",
"SUSPENDED",
"EXPIRED",
"INACTIVE"
]
}
}
},
"originalWalletTransaction": {
"additionalPayloadValues": {
"default": {
"state": "MODIFIED"
}
}
},
"walletTransaction": {
"additionalPayloadValues": {
"default": {
"type": "PRODUCT_EXCHANGE"
}
}
}
},
"refund": {
"allowUnknownBasketContents": false,
"filters": {
"accounts": {
"default": {
"status": [
"ACTIVE",
"LOCKED",
"EXPIRED",
"INACTIVE"
],
"accountType": [
"COUPON_ECOUPON",
"STORED_VALUE_VOUCHER",
"STORED_VALUE_DEBIT",
"STORED_VALUE_PLASTIC",
"LOYALTY_POINTS",
"COUPON_CONTINUITY",
"COUPON_STAMP_CARD",
"COUPON_MULTI_PROMOTION_COUPON",
"COUPON_QUEST"
],
"campaignsStatus": [
"ACTIVE",
"SUSPENDED",
"READY",
"EXPIRED"
]
}
}
},
"originalWalletTransaction": {
"additionalPayloadValues": {
"default": {
"state": "MODIFIED"
}
}
},
"walletTransaction": {
"additionalPayloadValues": {
"default": {
"type": "REFUND"
}
}
}
},
"rules": {
"ordering": [
{
"type": "CAMPAIGN_TAG",
"config": [
"PriorityOffer",
"SecondaryOffer"
]
},
{
"type": "OFFER_TYPE",
"config": [
"FIXED_AMOUNT_OFF_PRODUCTS",
"VARIABLE_AMOUNT_OFF_PRODUCTS",
"FIXED_PRICE_PRODUCTS",
"FREE_PRODUCTS",
"MEAL_DEAL",
"FIXED_PERCENTAGE_OFF_PRODUCTS",
"FIXED_AMOUNT_OFF_BASKET",
"FIXED_PERCENTAGE_OFF_BASKET",
"VARIABLE_AMOUNT_OFF_BASKET",
"FIXED_PERCENTAGE_OFF_BASKET",
"POINTS_EXCHANGE_DISCOUNT_OFF_PRODUCTS",
"FIXED_POINTS",
"FIXED_POINTS_PRODUCTS",
"VARIABLE_POINTS_PRODUCTS",
"VARIABLE_POINTS_BASKET",
"FIXED_POINTS_BASKET",
"CONTINUITY",
"NON_TRANSACTIONAL",
"STAMP_CARD",
"BOUNCE_BACK",
"ZERO_REWARD",
"QUEST_FIXED_POINTS",
"MULTI_PROMOTION_DISCOUNT"
]
},
{
"type": "VALUE",
"direction": "desc"
},
{
"type": "VALID_TO",
"direction": "asc"
}
]
},
"settle": {
"batchCreateRedeem": true,
"redeemAccountTransaction": {
"includeNumberOfRewards": {
"enabled": true
}
},
"filters": {
"accounts": {
"default": {
"state": [
"LOADED",
"EARNONLY",
"EARNBURN",
"HIDDEN"
],
"status": [
"ACTIVE",
"LOCKED"
],
"accountType": [
"COUPON_ECOUPON",
"COUPON_CONTINUITY"
],
"campaignsStatus": [
"ACTIVE",
"EXPIRED",
"SUSPENDED"
]
}
}
},
"walletTransaction": {
"additionalPayloadValues": {
"default": {
"type": "SETTLE"
}
},
"includeTokenAccountTransactions": {
"enabled": true
}
}
},
"spend": {
"walletTransaction": {
"additionalPayloadValues": {
"default": {
"state": "ORIGINAL",
"status": "ACTIVE",
"type": "SPEND"
}
}
}
},
"spendCalculate": {
"filters": {
"accounts": {
"default": {
"state": [
"LOADED",
"EARNONLY",
"EARNBURN",
"HIDDEN"
],
"status": [
"ACTIVE",
"LOCKED"
],
"accountType": [
"COUPON_ECOUPON",
"LOYALTY_POINTS"
],
"campaignsStatus": [
"READY",
"ACTIVE",
"EXPIRED",
"SUSPENDED"
]
}
}
}
}
}
},
"security": {
"unitCredentials": [
{
"name": "api",
"clientId": "yyyyy",
"secret": "zzzzz",
"status": "ACTIVE",
"locked": "Y",
"dateCreated": "2025-06-10T17:31:08+00:00",
"lastUpdated": "2025-06-10T17:31:08+00:00"
}
]
},
"unitCodeProviders": [
1,
19,
106
],
"tiers": {
"enabled": true,
"mode": "INDIVIDUAL",
"baseEarn": {
"enabled": true
},
"campaign": {
"enabled": true
}
},
"walletConfig": {
"wallets": {
"clientTypes": [
{
"walletTypeId": "2690",
"unitId": "171660",
"name": "CONSUMER",
"configuration": {
"allowMerge": {
"value": "1",
"type": "integer",
"description": "This wallet type can not merge into other wallets"
},
"defaultAccountState": {
"value": "UNLOADED",
"type": "string",
"description": "The default state for all accounts other than those overridden is UNLOADED"
},
"defaultAccountStateTypeLoyaltyPoints": {
"value": "EARNONLY",
"type": "string",
"description": "The default state for points accounts is EARNONLY"
},
"defaultConsumerType": {
"value": "INDIVIDUAL",
"type": "string",
"description": "The default type of consumer for this wallet type"
},
"defaultState": {
"value": "DEFAULT",
"type": "string",
"description": "The default state when creating"
},
"defaultStatus": {
"value": "ACTIVE",
"type": "string",
"description": "The default status when creating"
},
"maxAssociate": {
"value": "10",
"type": "integer",
"description": "This wallet type can not be an associate of any other wallet type"
},
"maxChild": {
"value": "1",
"type": "integer",
"description": "This wallet type can not be a child of any other wallet"
},
"maxParent": {
"value": "0",
"type": "integer",
"description": "This wallet type can not be a parent of any other wallet"
}
}
}
],
"clientStates": [
{
"walletClientStateId": "3498",
"unitId": "171660",
"name": "DEFAULT",
"description": "The wallet is in the state of DEFAULT",
"dateCreated": "2025-06-10T17:31:08+00:00",
"lastUpdated": null
}
]
},
"walletIdentities": {
"clientTypes": [
{
"identityTypeId": "4628",
"unitId": "171660",
"name": "CUSTOMER_ID",
"configuration": {
"defaultStatus": {
"value": "ACTIVE",
"type": "string",
"description": "The default state of this identity when creating"
},
"defaultState": {
"value": "EARNBURN",
"type": "string",
"description": "The default state of this identity when creating"
}
},
"properties": []
},
{
"identityTypeId": "4629",
"unitId": "171660",
"name": "CARD",
"configuration": {
"defaultStatus": {
"value": "ACTIVE",
"type": "string",
"description": "The default state of this identity when creating"
},
"defaultState": {
"value": "EARNBURN",
"type": "string",
"description": "The default state of this identity when creating"
}
},
"properties": []
},
{
"identityTypeId": "4630",
"unitId": "171660",
"name": "MOBILE",
"configuration": {
"defaultStatus": {
"value": "ACTIVE",
"type": "string",
"description": "The default state of this identity when creating"
},
"defaultState": {
"value": "EARNONLY",
"type": "string",
"description": "The default state of this identity when creating"
}
},
"properties": []
},
{
"identityTypeId": "4631",
"unitId": "171660",
"name": "EMAIL",
"configuration": {
"defaultStatus": {
"value": "ACTIVE",
"type": "string",
"description": "The default state of this identity when creating"
},
"defaultState": {
"value": "EARNBURN",
"type": "string",
"description": "The default state of this identity when creating"
}
},
"properties": []
}
],
"clientStates": [
{
"identityClientStateId": "3234",
"unitId": "171660",
"name": "EARNONLY",
"description": "The identity has a state of EARNONLY",
"dateCreated": "2025-06-10T17:31:08+00:00",
"lastUpdated": null
},
{
"identityClientStateId": "3235",
"unitId": "171660",
"name": "EARNBURN",
"description": "The identity has a state of EARNBURN",
"dateCreated": "2025-06-10T17:31:08+00:00",
"lastUpdated": null
}
]
},
"walletTransactions": {
"clientTypes": [
{
"walletTransactionTypeId": "8174",
"unitId": "171660",
"name": "ADJUSTMENT",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8175",
"unitId": "171660",
"name": "AUTO_EXCHANGE",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8176",
"unitId": "171660",
"name": "BEHAVIOURAL_ACTION_POINTS",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8177",
"unitId": "171660",
"name": "BEHAVIOURAL_ACTION_COUPON",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8178",
"unitId": "171660",
"name": "CHALLENGE_REWARD",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8179",
"unitId": "171660",
"name": "CREDIT",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8180",
"unitId": "171660",
"name": "DEBIT",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8181",
"unitId": "171660",
"name": "DONATION",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8182",
"unitId": "171660",
"name": "EXCHANGE",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8183",
"unitId": "171660",
"name": "EXPIRY",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8184",
"unitId": "171660",
"name": "FULFIL",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8185",
"unitId": "171660",
"name": "GAME_REWARD",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8186",
"unitId": "171660",
"name": "GIFT",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8187",
"unitId": "171660",
"name": "GOODWILL",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8188",
"unitId": "171660",
"name": "PRODUCT_EXCHANGE",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8189",
"unitId": "171660",
"name": "REDEEM_CREDIT",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8190",
"unitId": "171660",
"name": "REFUND",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8191",
"unitId": "171660",
"name": "SETTLE",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8192",
"unitId": "171660",
"name": "SPEND",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "ACTIVE",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8193",
"unitId": "171660",
"name": "SUBSCRIPTION_CREATED",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8194",
"unitId": "171660",
"name": "SUBSCRIPTION_RENEWED",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8195",
"unitId": "171660",
"name": "SUBSCRIPTION_CANCELLED",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8196",
"unitId": "171660",
"name": "UNREDEEM",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
},
{
"walletTransactionTypeId": "8197",
"unitId": "171660",
"name": "VOID",
"configuration": {
"defaultState": {
"value": "ORIGINAL",
"type": "string",
"description": "The default state of the transaction when creating"
},
"defaultStatus": {
"value": "SETTLED",
"type": "string",
"description": "The default status of the transaction when creating"
}
}
}
],
"clientStates": [
{
"walletTransactionClientStateId": "2582",
"unitId": "171660",
"name": "ORIGINAL",
"description": "The wallet transaction is in its original state",
"dateCreated": "2025-06-10T17:31:08+00:00",
"lastUpdated": null
},
{
"walletTransactionClientStateId": "2583",
"unitId": "171660",
"name": "MODIFIED",
"description": "The wallet transaction has been modified",
"dateCreated": "2025-06-10T17:31:08+00:00",
"lastUpdated": null
}
]
},
"walletConsumers": {
"clientTypes": [
{
"walletConsumerTypeId": "2352",
"unitId": "171660",
"name": "INDIVIDUAL",
"configuration": {
"defaultState": {
"value": "DEFAULT",
"type": "string",
"description": "The consumer state is default"
},
"defaultStatus": {
"value": "ACTIVE",
"type": "string",
"description": "The consumer status is active"
}
}
}
],
"clientStates": [
{
"walletConsumerClientStateId": "2892",
"unitId": "171660",
"name": "DEFAULT",
"description": "The defaults state of a consumer",
"dateCreated": "2025-06-10T17:31:08+00:00",
"lastUpdated": null
}
],
"dataKeys": [
{
"walletConsumerDataKeyId": "12726",
"unitId": "171660",
"dataKey": "personal.title",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12727",
"unitId": "171660",
"dataKey": "personal.firstName",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12728",
"unitId": "171660",
"dataKey": "personal.lastName",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12729",
"unitId": "171660",
"dataKey": "personal.preferredName",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12730",
"unitId": "171660",
"dataKey": "personal.language",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12731",
"unitId": "171660",
"dataKey": "personal.gender",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12732",
"unitId": "171660",
"dataKey": "personal.birthDate",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12733",
"unitId": "171660",
"dataKey": "address.default.type",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12734",
"unitId": "171660",
"dataKey": "address.default.line1",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12735",
"unitId": "171660",
"dataKey": "address.default.line2",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12736",
"unitId": "171660",
"dataKey": "address.default.line3",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12737",
"unitId": "171660",
"dataKey": "address.default.city",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12738",
"unitId": "171660",
"dataKey": "address.default.county",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12739",
"unitId": "171660",
"dataKey": "address.default.postcode",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12740",
"unitId": "171660",
"dataKey": "address.default.state",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12741",
"unitId": "171660",
"dataKey": "address.default.country",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12742",
"unitId": "171660",
"dataKey": "contact.email.default",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12743",
"unitId": "171660",
"dataKey": "contact.phone.default",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12744",
"unitId": "171660",
"dataKey": "communication.default.optin.admin",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12745",
"unitId": "171660",
"dataKey": "communication.default.optin.marketing",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12746",
"unitId": "171660",
"dataKey": "communication.email.optin.admin",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12747",
"unitId": "171660",
"dataKey": "communication.email.optin.marketing",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12748",
"unitId": "171660",
"dataKey": "communication.push.optin.admin",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12749",
"unitId": "171660",
"dataKey": "communication.push.optin.marketing",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12750",
"unitId": "171660",
"dataKey": "communication.sms.optin.admin",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12751",
"unitId": "171660",
"dataKey": "communication.sms.optin.marketing",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12752",
"unitId": "171660",
"dataKey": "consent.profiling.optin",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12753",
"unitId": "171660",
"dataKey": "consent.mobileAppTerms.accepted",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "boolean"
},
{
"walletConsumerDataKeyId": "12754",
"unitId": "171660",
"dataKey": "preference.store.0.brand",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12755",
"unitId": "171660",
"dataKey": "preference.store.0.outlets",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "array"
},
{
"walletConsumerDataKeyId": "12756",
"unitId": "171660",
"dataKey": "preference.store.1.brand",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "string"
},
{
"walletConsumerDataKeyId": "12757",
"unitId": "171660",
"dataKey": "preference.store.1.outlets",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "array"
},
{
"walletConsumerDataKeyId": "12758",
"unitId": "171660",
"dataKey": "segmentation.demographic",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "array"
},
{
"walletConsumerDataKeyId": "12759",
"unitId": "171660",
"dataKey": "segmentation.geographic",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "array"
},
{
"walletConsumerDataKeyId": "12760",
"unitId": "171660",
"dataKey": "segmentation.audiences",
"encrypted": 0,
"searchable": 1,
"updateable": 1,
"viewable": 1,
"validation": null,
"parentWalletConsumerDataKeyId": null,
"walletConsumerDataTypeId": null,
"walletConsumerDataType": "array"
}
]
},
"walletInvites": {
"clientTypes": [
{
"walletInviteTypeId": "1567",
"unitId": "171660",
"name": "INVITE",
"configuration": {
"defaultState": {
"value": "INVITE",
"type": "string",
"description": "The consumer state is invite"
},
"defaultStatus": {
"value": "ACTIVE",
"type": "string",
"description": "The consumer status is active"
}
},
"properties": []
}
],
"clientStates": [
{
"walletInviteClientStateId": "2301",
"unitId": "171660",
"name": "INVITE",
"description": "The invite state is INVITE",
"dateCreated": "2025-06-10T17:31:09+00:00",
"lastUpdated": null
}
]
},
"walletAccounts": {
"clientTypes": [
{
"accountClientTypeId": "3732",
"unitId": "171660",
"name": "BEHAVIOURAL_ACTION",
"configuration": []
},
{
"accountClientTypeId": "3733",
"unitId": "171660",
"name": "GAME_ENTRY",
"configuration": []
},
{
"accountClientTypeId": "3734",
"unitId": "171660",
"name": "OFFER",
"configuration": []
},
{
"accountClientTypeId": "3735",
"unitId": "171660",
"name": "RETAILPOINTS",
"configuration": []
}
],
"clientStates": [
{
"accountClientStateId": "3298",
"unitId": "171660",
"name": "LOADED",
"description": "The account is loaded for the next transaction",
"dateCreated": "2025-06-10T17:31:09+00:00",
"lastUpdated": null
},
{
"accountClientStateId": "3299",
"unitId": "171660",
"name": "UNLOADED",
"description": "The account is unloaded and will not play in the next transaction",
"dateCreated": "2025-06-10T17:31:09+00:00",
"lastUpdated": null
},
{
"accountClientStateId": "3300",
"unitId": "171660",
"name": "HIDDEN",
"description": "The account is set to play in the next transaction but is hidden from customer view",
"dateCreated": "2025-06-10T17:31:09+00:00",
"lastUpdated": null
},
{
"accountClientStateId": "3301",
"unitId": "171660",
"name": "EARNBURN",
"description": "The account is set to points only",
"dateCreated": "2025-06-10T17:31:09+00:00",
"lastUpdated": null
},
{
"accountClientStateId": "3302",
"unitId": "171660",
"name": "EARNONLY",
"description": "The account is set to earn and burn points",
"dateCreated": "2025-06-10T17:31:09+00:00",
"lastUpdated": null
}
]
}
}
}
The security.unitCredentials array will only be presented at the time of the opt level Company unit create on this call. Take note of the clientId and secret values.
Step 3: Create Your Banners (Redemption Partners)
Banners represent your store groups, franchises, or partner brands. They sit under your main brand and group multiple stores for campaign and loyalty targeting.
- 3.1 Note the clientId and secret values from the security.unitCredentials array in the response from Step 2
- 3.2 Input clientId and secret values in your API platform to continue creating redemption partners and outlets
- 3.3 Get the id provided in the response from Step 2
- Use that for the parentUnitId in this API call
- 3.4 Enter the following additional required objects:
- name
- Select a unique alphanumeric identifier (no dashes) as incomingIdentifier
- Use COMPANY as type
- Use ACTIVE as status to start using this unit immediately
Step 4: Call POST /units
Repeat this step for every banner needed
{
"name": "Fabulous Retailer",
"incomingIdentifier": "fabulousretailer",
"type": "COMPANY",
"status": "ACTIVE",
"parentUnitId": "171660"
}{
"id": "171661",
"name": "Fabulous Retailer",
"safeName": "fabulousinc-fabulousretailer",
"type": "COMPANY",
"status": "ACTIVE",
"unitRelations": [
{
"unitRelatedId": "171660",
"relationType": "PARENT"
}
],
"reference": "fabulousretailer",
"tags": [],
"outgoingIdentifier": "fabulousretailer",
"incomingIdentifier": "fabulousretailer",
"timezones": {
"default": "UTC"
}
}Step 5: Create Your Stores (Outlets)
Stores are the individual locations where customers earn and redeem points and offers. They sit under banners in your company structure.
- 5.1 Capture the id provided in the response from Step 4
- Use that for the parentUnitId in this API call
- 5.2 Enter the following required objects:
- name
- Select a unique alphanumeric identifier (no dashes) as incomingIdentifier
- Use OUTLET as type
- Use ACTIVE as status to start using this outlet immediately
Repeat this step for every outlet needed.
{
"name": "Store 100",
"incomingIdentifier": "store100",
"type": "OUTLET",
"status": "ACTIVE",
"parentUnitId": "171661"
}{
"id": "171662",
"name": "Store 100",
"safeName": "fabulousinc-fabulousretailer-store100",
"type": "OUTLET",
"status": "ACTIVE",
"unitRelations": [
{
"unitRelatedId": "171661",
"relationType": "PARENT"
}
],
"reference": "store100",
"tags": [],
"outgoingIdentifier": "store100",
"incomingIdentifier": "store100",
"timezones": {
"default": "UTC"
}
}✅ Business Readiness Checklist
Use these checks to confirm your brand, banners, and stores are set up correctly:
- Retrieve each unit using GET units/unitId to confirm it exists under the correct parent brand or banner
- Check the tiers object to ensure it is enabled and set to INDIVIDUAL
- Confirm each banner and store is showing ACTIVE status for immediate use
🔧 Troubleshooting Tips
Issue | Possible Cause & Resolution |
|---|---|
Unit created under wrong parent | Set the incorrect unit to INACTIVE using PATCH /units/unitId API, then create a new unit with a unique identifier |
Unit Not Found (404) | The unit may not belong to the parent for the clientId used. Verify your clientId and secret before retrying. |
Duplicate incomingIdentifier Error | The incomingIdentifier is already used by another unit under the same parent. Select a new unique identifier |
Updated about 5 hours ago