Account Data Structures

The below data model outlines the structure of accounts in AIR with how an account relates to its immediately neighbouring objects.

Resources

Resources are a collection of data objects that describe how it can be used. Each of these are outlined below

Campaigns

A campaign is a data object that describes a coupon and how it can be used, the qualification criteria that needs to be met for a customer to be eligable for a reward, the reward criteria of what the customer gets etc.

Examples:

Get 100 points for purchasing a toaster
Get 50 points per can of cola purchased
Get a £1 discount for buying a specified product

See our Campaigns best practice guide for more details on campaigns.

Plan

A plan is akin to a grouping of campaigns that are linked, issued and can be removed together. They are most frequently used for subscription services. For example, join our premium club and get extra rewards including:

Free shipping
£5 off a £50 spend coupon
1.5x Points multiplier on your basket spend

Scheme

A scheme is a data object describing how points work. Many items can be set up against a scheme including but limited to:

Base Earn rules
Points Spend rules
Goodwill rules
Limitations on the points account
Points Expiry rules

Schemes differ from all other resources in that a customer can only ever have one account from a given scheme in their wallet at any time. All the others allow multiple.

Programme

A Programme describes the rules for a Stored value account. This can be things like:

Where the value can be used
The maximum allowed balances
The maximum allowed amount to be spent in a single transaction

Accounts

An account is an instance of a Resource given to a customer. It may be placed inside a customer's wallet or have a token code attached to it (or both) for the customer to use.

Accounts come in different types depending on the nature of the resource to which they are linked.

Accounts all have a standard basic structure that are extended based on their type and sub-type.

Coupon

A coupon account can have several "sub-types":

ECOUPON

{
    "accountId": "4079980101",
    "walletId": "215997392",
    "campaignId": "100343475",
    "type": "ECOUPON",
    "clientType": "OFFER",
    "status": "ACTIVE",
    "state": "LOADED",
    "dates": {
        "start": "2025-01-13T18:14:29+00:00",
        "end": "2030-12-31T23:59:00+00:00"
    },
    "meta": [],
    "dateCreated": "2025-01-13T18:14:29+00:00",
    "lastUpdated": "2025-01-13T18:14:29+00:00",
    "overrides": [],
    "balances": {
        "available": 0,
        "refundable": 0
    },
    "relationships": [],
    "mobileWallet": "https://sb.uk.mypass.is/a/xxxx/xxxx"
}

CONTINUITY

{
    "accountId": "4124878243",
    "walletId": "215997392",
    "campaignId": "100494312",
    "type": "CONTINUITY",
    "clientType": "OFFER",
    "status": "ACTIVE",
    "state": "LOADED",
    "dates": {
        "start": "2025-02-05T15:28:23+00:00",
        "end": "2030-12-31T23:59:00+00:00"
    },
    "meta": [],
    "dateCreated": "2025-02-05T15:28:23+00:00",
    "lastUpdated": "2025-02-05T15:28:23+00:00",
    "overrides": [],
    "balances": {
        "totalSpend": 0,
        "currentSpend": 0,
        "transactionCount": 0,
        "currentTransactions": 0,
        "totalUnits": 0,
        "currentUnits": 0
    },
    "relationships": [],
    "mobileWallet": "https://sb.uk.mypass.is/a/xxxx/xxxx"
}

STAMP_CARD

{
    "accountId": "4124878293",
    "walletId": "215997392",
    "campaignId": "100440283",
    "type": "COUPON_STAMP_CARD",
    "clientType": "OFFER",
    "status": "ACTIVE",
    "state": "LOADED",
    "dates": {
        "start": "2025-02-05T15:33:31+00:00",
        "end": "2030-12-31T23:59:00+00:00"
    },
    "meta": [],
    "dateCreated": "2025-02-05T15:33:31+00:00",
    "lastUpdated": "2025-02-05T15:33:31+00:00",
    "overrides": [],
    "balances": {
        "available": 0,
        "refundable": 0
    },
    "relationships": [],
    "mobileWallet": "https://sb.uk.mypass.is/a/xxx/xxxx"
}

QUEST

{
    "accountId": "4124878255",
    "walletId": "215997392",
    "campaignId": "100104953",
    "type": "QUEST",
    "clientType": "OFFER",
    "status": "ACTIVE",
    "state": "LOADED",
    "dates": {
        "start": "2025-02-05T15:30:10+00:00",
        "end": "2025-03-06T23:59:00+00:00"
    },
    "meta": [],
    "dateCreated": "2025-02-05T15:30:10+00:00",
    "lastUpdated": "2025-02-05T15:30:10+00:00",
    "overrides": [],
    "balances": {
        "objectivesMet": 0
    },
    "relationships": {
        "OBJECTIVE": {
            "ECOUPON": [
                {
                    "accountId": "4124878256",
                    "dateCreated": "2025-02-05T15:30:10+00:00"
                },
                {
                	  "accountId": "4124878257",
                    "dateCreated": "2025-02-05T15:30:10+00:00"
                }
            ]
        }
    },
    "mobileWallet": "https://sb.uk.mypass.is/a/xxxx/xxxx"
}

BEHAVIOURAL_ACTION

{
    "accountId": "4124880694",
    "walletId": "215997392",
    "campaignId": "1667163",
    "type": "BEHAVIOURAL_ACTION",
    "clientType": null,
    "status": "USED",
    "state": "LOADED",
    "dates": {
        "start": "2025-02-05T16:14:39+00:00",
        "end": "2038-01-19T03:14:07+00:00"
     },
    "meta": [],
    "dateCreated": "2025-02-05T16:14:39+00:00",
    "lastUpdated": "2025-02-05T16:14:39+00:00",
    "overrides": [],
    "balances": {
        "available": 0,
        "refundable": 0
    },
    "relationships": [],
    "mobileWallet": "https://sb.uk.mypass.is/a/xxxx/xxxx"
}

Subscription

A subscription account only has one sub-type:

STANDARD_SUBSCRIPTION

This account type has relationships to the entitlements to which it is linked. Actions taken on the "parent" account feed down to the entitlements. For example, cancelling a STANDARD_SUBSCRIPTION account will cancel all the associated entitlements.

{
    "accountId": "4124877886",
    "walletId": "215997392",
    "campaignId": "1741279",
    "type": "STANDARD_SUBSCRIPTION",
    "clientType": "SUBSCRIPTION",
    "status": "ACTIVE",
    "state": "LOADED",
    "dates": {
        "start": "2025-02-05T15:22:58+00:00",
        "end": "2038-01-19T03:14:07+00:00"
    },
    "meta": [],
    "dateCreated": "2025-02-05T15:22:58+00:00",
    "lastUpdated": "2025-02-05T15:22:58+00:00",
    "overrides": [],
    "balances": null,
    "relationships": {
        "ENTITLEMENT": {
            "ECOUPON": [
                {
                    "accountId": "4124877887",
                    "dateCreated": "2025-02-05T15:22:58+00:00"
                }
            ]
        }
    },
    "mobileWallet": "https://sb.uk.mypass.is/a/xxx/xxx"
}

Points

A points account has a balances object inside it that tracks all the points balances. The different balances are listed below:

Balance Name	Description
current	The total balance of the account
usable	The balance of hte account that can be used at any one time. This will exclude any locked or pending points.
locked	The balance of points that are currently locked to a transaction and can not be used outside of that transaction
lifetime	This number only goes up. When the curent balance of the account increases so does this balance. It keeps a lifetime track of the number of points an account has been credited into it.
lifetimeSpend	The lifetime spend of the account. How many points have been reduced from the account in it's lifetime.
lifetimeSpendValue	The monetary value of the points that have been spent from the account.
pending	The number of points that have not yet been released to a customer to be used.

Points accounts differ from other account types in that only a single points account from a scheme can be added to a wallet. This is to protect against over earning of points for base earn. It is allowed to have other points accounts for other schemes but only one per scheme is allowed.

{
    "accountId": "4079980102",
    "walletId": "215997392",
    "campaignId": "1577698",
    "type": "POINTS",
    "clientType": "RETAILPOINTS",
    "status": "ACTIVE",
    "state": "EARNBURN",
    "dates": {
        "start": "2025-01-13T18:14:29+00:00",
        "end": "2038-01-19T03:14:07+00:00"
    },
    "meta": [],
    "dateCreated": "2025-01-13T18:14:29+00:00",
    "lastUpdated": "2025-01-13T18:14:29+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/xxxx/xxxxxx"
}

Stored Value

A stored value account is similar to a points account in that it has balances stored against it. The balance of a stored value account represents a monetary figure in the lowest denomination of currency. For example, a balance of 1040 means £10.40p (ten pounds and fourty pence).

All stored value accounts have the same structure.

📘
Tokens
The tokens block in a stored value account will be returned if the query parameter ?tokens=true is added to the request and the account has a token value associated with it.

{
    "accountId": "4124875224",
    "walletId": "215997392",
    "campaignId": "100574345",
    "type": "VOUCHER",
    "clientType": null,
    "status": "ACTIVE",
    "state": "LOADED",
    "dates": {
        "start": "2025-02-05T15:17:08+00:00",
        "end": "2038-01-19T03:14:07+00:00"
    },
    "meta": [],
    "dateCreated": "2025-02-05T15:17:08+00:00",
    "lastUpdated": "2025-02-05T15:17:08+00:00",
    "overrides": [],
    "balances": {
        "available": 0,
        "refundable": 0
    },
    "relationships": [],
    "mobileWallet": "https://sb.uk.mypass.is/a/xxxx/xxxx",
    "tokens": [
        {
            "tokenId": "772028557",
            "accountId": "4124875224",
            "token": "7666182756",
            "validFrom": "2025-02-05T15:17:08+00:00",
            "validTo": "2038-01-19T03:14:07+00:00",
            "dateCreated": "2025-02-05T15:17:08+00:00",
            "lastUpdated": "2025-02-05T15:17:08+00:00",
            "status": "ACTIVE",
            "tokenLock": {
                "validFrom": null,
                "validTo": null
            }
        }
    ],
    "stats": null,
    "limits": null,
    "relatedAccounts": null,
    "createTransaction": null
}

Voucher

Voucher accounts are used for stored value accounts that do not need to have a plastic card associated with them that use the BIN code number ranges. This type covers most use cases for stored value.

Plastic

If there is a requirement to use a BIN and Scheme ranged card number for the stored value account, a plastic programme type supports this. The account generated has a type of "PLASTIC" but behaves in the same way as a VOUCHER account.