Scheme Services

When creating a scheme via API, the services object will help you define rules to manage points budgets, goodwill, points expiry and gifting.

Budgets

Budgets can be assigned to loyalty transactions, so when that transaction occurs the points will be associated with that budget. If any are enabled, the following configuration can be set:

• The default fund(s) that should be used for these transaction types
• The fund(s) the points are added from

Transaction Types

Funds can be assigned to any of following transaction types, along with a reason code.

• autoTopup
• credit
• debit
• goodwill
• spend
• earn
• gift
• expiryPoints

Let's say the Fabulous Retailer wanted to set all points that were credited to a specific budget, using two reason codes: one for the marketing department and another for merchandising. The retailer can specify when to use these two reason codes throughout different credit actions. After setting enabled to true in the services.credit object, list the fundingAccountId, fundingPercentage and include at least one reason.

{
  "credit": {
    "enabled": true,
    "defaultFunding": {
      "enabled": true,
      "funds": [
        {
          "fundingAccountId": "222917",
          "fundingPercentage": 100
        }
      ]
    },
    "reasons": {
      "FAB100": {
        "enabled": true,
        "description": null,
        "funds": [
          {
            "fundingAccountId": "248486",
            "fundingPercentage": 100
          }
        ]
      },
      "FAB200": {
        "enabled": true,
        "description": null,
        "funds": [
          {
            "fundingAccountId": "248486",
            "fundingPercentage": 100
          }
        ]
      }
    },
    "restrictions": []
  }
}

Goodwill Restrictions

Goodwill grants retailers the ability to award a number of points to scheme members as a gesture of goodwill. To protect against fraud, there are rules that can be set around the number of points a consumer can be issued and the number of times goodwill can be issued in a given time frame. Within the services.goodwill object, the restrictions object will allow you to house the rules.

Here is an example where goodwill restrictions allow the following limits on goodwill transactions and points issuance:

• The rolling period is set to 365 days
• Maximum of 7,500 points can be credited per rolling period
• A wallet can have a maximum of 10 goodwill transactions in the rolling period
• No more than 1,000 points can be credited on a single transaction

{
  "goodwill": {
    "enabled": false,
    "defaultFunding": null,
    "reasons": null,
    "restrictions": [
      {
        "period": 365,
        "metric": "DAYS",
        "transactions": 10,
        "value": 7500,
        "singleValue": 1000
      }
    ]
  }
}

Points Expiry Rules

AIR allows clients the ability to segment points in a points account to automatically expire when points expiry rules are met.

When Points Expiry rules are enabled on a Scheme (services.expiryPoints.enabled = true), each time points are earned, these are stored in Points Ledger. Along with the amount of points, a date / time is calculated based on the Points Expiry rules set at the time the points were earned. AIR uses a first in, first out methodology to determine which points will expire first. The oldest points will expire from the points account first.

📘

If points expiry is anticipated to be used in a scheme, they should be enabled at the time of scheme create.

If the Points Expiry rules are changed, then it will not affect points already earned as these will maintain the date calculated at the time of earning, but all future points earned will pick up the updated points expiry rules. The below table highlights the key objects in the expiryPoints rule object.

*See Loyalty Ledger & Tiers for more information on Points Expiry.

📘

Points added to a points account during account creation do not have an expiry date.

MONTHEND points expiry example:

• Points earned can be used in a six month period
• The expiry date of the points will be the last day of the sixth month
• Consider the following customer example:
  • Gemma earns 175 points on a SETTLE transaction on 2 January 2025 and 250 points on 15 March 2025 on a single transaction via a SETTLE transaction
    • Points expiry date for the 175 points earned on the 2 January transaction is 31 July 2025 23:59:59
    • Points expiry date for the 250 points earned on the 15 March 2025 transaction is 30 September 2025 23:59:59

{
  "expiryPoints": {
    "enabled": true,
    "rule": {
      "periodCount": 6,
      "periodType": "MONTH",
      "rounding": "MONTHEND",
      "type": "CUTOFFDATE"
    }
  }
}

YEAREND points expiry example:

• Points earned can be used in a 12 month period
• The expiry date of the points will be the last day of the year
• Consider the following customer example:
  • Gemma earns 175 points on a SETTLE transaction on 2 December 2024 and 250 points on 15 March 2025 on a single transaction via a SETTLE transaction
    • Points expiry date for the 175 points earned on the 2 December 2024 transaction is 31 December 2025 23:59:59
    • Points expiry date for the 250 points earned on the 15 March 2025 transaction is 31 December 2026 23:59:59

{
  "expiryPoints": {
    "enabled": true,
    "rule": {
      "periodCount": 12,
      "periodType": "MONTH",
      "rounding": "YEAREND",
      "type": "CUTOFFDATE"
    }
  }
}

ABSOLUTE points expiry example:

• Points earned can be used 90 days after the credit
• The expiry date of the points will be exactly 90 days after the credit event
• Consider the following customer example:
  • Gemma earns 175 points on a SETTLE transaction on 2 January 2025 and 250 points on 15 March 2025 on a single transaction via a SETTLE transaction
    • Points expiry date for the the 175 points earned on the 2 January 2025 transaction is 2 April 2025
    • Points expiry date for the 250 points earned on the 15 March 2025 transaction is 13 June 2025 23:59:59

{
  "expiryPoints": {
    "enabled": true,
    "rule": {
      "periodCount": 90,
      "periodType": "DAY",
      "rounding": "ABSOLUTE",
      "type": "CUTOFFDATE"
    }
  }
}

SETDATE points expiry example:

• Points earned can be used through a fixed date in the future
• The expiry date of points will be 30 September 2025
• Gemma earns 250 on 15 March 2025 on a single transaction via a SETTLE transaction
  • Points expiry date for this set of points is 30 September 2025

{
  "expiryPoints": {
    "enabled": true,
    "rule": {
      "date": "2025-09-30 23:59:00",
      "type": "SETDATE"
    }
  }
}

ACTIVITY points expiry example:

• Points earned can expire when there is a set amount of days that pass with no activity in the wallet
• Activity in the wallet is defined as an of the following wallet transaction types:

• Example A: activityPararmeters are setup with any wallet transaction type
  • Gemma earns 250 points on 15 March 2025 on a single transaction via a SETTLE transaction
  • Gemma does not engage with the loyalty programme for 120 days
  • The 250 points earned expire on 13 July 2025
• Example B: activityPararmeters are setup with only the following wallet transaction types:
  • CREDIT, DEBIT, EXCHANGE, FULFIL, SETTLE and SPEND
  • Scenario 1: Gemma earns 250 points on 15 March 2025 on a single transaction via a SETTLE transaction
    • Gemma does not engage with the loyalty programme for 120 days, resulting in no new wallet transactions
    • The 250 points earned expire on 13 July 2025
  • Scenario 2: Gemma earns 250 points on 15 March 2025 on a single transaction via a SETTLE transaction
    • Gemma has a GOODWILL transaction that is created in the wallet on 12 June 2025
    • The 250 points earned expire on 13 July 2025, as none of the six selected walletTransactionTypes were created 120 days after the SETTLE
  • Scenario 3: Gemma earns 250 points on 15 March 2025 on a single transaction via a SETTLE transaction
    • Gemma has a SETTLE transaction that is created in the wallet on 12 June 2025
    • The 120 day counter is reset and new earliest potential expiration date for all points in the loyalty account is 10 October 2025

{
  "expiryPoints": {
    "enabled": true,
    "rule": {
      "periodCount": 120,
      "periodType": "DAY",
      "activityParameters": {
        "walletTransactions": {
          "enabled": true,
          "walletTransactionTypes": []
        }
      },
      "type": "ACTIVITY"
    }
  }
}

{
  "expiryPoints": {
    "enabled": true,
    "rule": {
      "periodCount": 120,
      "periodType": "DAY",
      "activityParameters": {
        "walletTransactions": {
          "enabled": true,
          "walletTransactionTypes": [
            "CREDIT",
            "DEBIT",
            "EXCHANGE",
            "FULFIL",
            "SETTLE",
            "SPEND"
          ]
        }
      },
      "type": "ACTIVITY"
    }
  }
}

For more information on points expiry periods for individual wallets, see the Retrieve Available Points API reference.

Gift

Points can be moved from one points account to another via a gift transaction. This can occur when one points account has earned points and the retailer offers the ability for a consumer to gift some or all of their points to another wallet.

Limits can be set by a count of days along with the maximum number of point a customer can gift from their wallet (outgoingGiftLimit) and the number of points a wallet can receive as a gift (incomingGiftLimit).

Consider this example:

The Fabulous Retailer offers a loyalty rewards scheme, where it allows consumers to earn points when shopping in store and then offering the ability in the Fabulous Rewards app to gift those points to a first responder in the local area as a thank you.

When enabled, the same period options are available for gift.outgoingGiftLimit.rule and gift.incomingGiftLimit.rule

📘

*graceTransaction is only valid in the gift.incomingGiftLimit.rule object

Gift points example:

• Gemma has 1,800 points in her wallet and wants to gift 200 points to a first responder in her city
• This is her first gift in the last 30 days
• Within the Fabulous Retailer's app, Gemma initiates the GIFT transaction
• Upon completion, the recipient points account is credited the 200 points
• Gemma's new point balance is 1,600

{
  "gift": {
    "outgoingGiftLimit": {
      "enabled": true,
      "rule": {
        "periodCount": 30,
        "periodType": "DAY",
        "points": 500,
        "rounding": "ABSOLUTE"
      }
    },
    "incomingGiftLimit": {
      "enabled": true,
      "rule": {
        "graceTransaction": true,
        "periodCount": 90,
        "periodType": "DAY",
        "points": 5000,
        "rounding": "ABSOLUTE"
      }
    }
  }
}

{
    "amount": 200,
    "accountId": "4464697679",
    "toWalletId": "241998515",
    "toAccountId": "4464631775"
}

{
  "walletTransactionId": "483433438",
  "parentWalletTransactionId": "0",
  "walletId": "242199701",
  "reference": "GIFT_6862c37eb235e5.89419166",
  "transactionDateTime": "2025-06-30T17:03:58+00:00",
  "transactionDateTimeOffset": "+00:00",
  "identityId": null,
  "identity": null,
  "type": "GIFT",
  "status": "SETTLED",
  "meta": null,
  "state": "ORIGINAL",
  "expiryDate": null,
  "accounts": [
    {
      "accountTransactionId": "8781370407",
      "parentAccountTransactionId": "",
      "accountId": "4464697679",
      "account": {
        "accountId": "4464697679",
        "walletId": "242199701",
        "campaignId": "101025502",
        "type": "POINTS",
        "clientType": "RETAILPOINTS",
        "status": "ACTIVE",
        "state": "EARNBURN",
        "dates": {
          "start": "2025-06-30T16:55:37+00:00",
          "end": "2038-01-19T03:14:07+00:00"
        },
        "meta": [],
        "dateCreated": "2025-06-30T16:55:37+00:00",
        "lastUpdated": "2025-06-30T17:03:58+00:00",
        "overrides": [],
        "balances": {
          "current": 1600,
          "usable": 1600,
          "lifetime": 10000,
          "pending": 0,
          "locked": 0,
          "lifetimeSpend": 0,
          "lifetimeSpendValue": 0
        },
        "relationships": [],
        "mobileWallet": "https://sb.uk.mypass.is/a/4464697679/3d2388235d7b069"
      },
      "event": "GIFT",
      "value": 200,
      "source": 1,
      "balancesBefore": {
        "current": 1800,
        "lifetime": 0
      },
      "balancesAfter": {
        "current": 1600,
        "lifetime": 0
      },
      "transactionDetails": [],
      "properties": [],
      "dateCreated": "2025-06-30T17:03:58+00:00",
      "lastUpdated": "2025-06-30T17:03:58+00:00"
    }
  ],
  "basket": {
    "contents": null,
    "summary": null,
    "payment": null
  },
  "channel": "api",
  "location": {
    "storeId": null,
    "storeParentId": null
  },
  "dateCreated": "2025-06-30T17:03:58+00:00",
  "lastUpdated": "2025-06-30T17:03:58+00:00"
}

Given the outgoingGiftLimit, if Gemma attempted to gift another 301 or more points, the scheme would prevent that request from succeeding.

{
  "errorMessage": "Rule Violation: The maximum number of points sendable as a gift (500) within the permitted time period (720 hours) will be exceeded.",
  "errorCode": "RV"
}

Exchange

Enabling exchange budgeting allows points earned form the scheme to be moved between partners when exchanging points for rewards. Different budgets and reason codes can be setup as needed.

{
  "exchange": {
    "enabled": true,
    "defaultFunding": {
      "enabled": true,
      "funds": [
        {
          "fundingAccountId": "1211789",
          "fundingPercentage": 100
        }
      ]
    },
    "reasons": null,
    "restrictions": []
  }
}

For more information on Exchanges, see Schemes Overview.