Skip to main content

Loyalty Card Management

Purpose of this document​

This document provides details at the business, technical (including configuration), and implementation levels for specific features within the ES Loyalty feature set. It covers a subset of functionality focused on Loyalty Card Management.

Table of contents​

General configuration​

  • Card limits configuration -- card_limits_config.json
  • Changes to configuration made to support Multiple Active Cards -- WIZ-4704

Physical/digital card number generation and allocation​

The system generates and allocates authentic card numbers for both physical and digital cards and assigns them to members.

When creating a new user, the system assigns a card number to them. For plastic cards, the system automatically assigns the number. For manually allocated cards, the card number must be provided explicitly when calling the registration API.

The system also uses a card pool -- a list of pre-generated card numbers that follow a specific format. The card pool determines how card numbers are assigned to users. The system loads generated card pools into the ES Loyalty DynamoDB table through a Jenkins Card Load Job.

  • An allocated card has been sent for printing. It must be manually assigned to an individual account by passing the card number to the registration API.
  • An unallocated card is available for digital assignment in the system.

Card validation check​

Card validation lists the attributes and values associated with a card type and validates the card type.

The system determines whether a card is valid for enrollment by checking that it meets one of the following conditions:

  • The card is allocated but not yet linked to an account.
  • The card is linked to an unregistered account.

Cards already linked to a registered account are considered invalid for enrollment.

Enrollment - issuing a physical card and associating it to an account​

When a user enrolls, the system associates a physical or digital card number with their account.

If enrollment takes place where a physical card is issued, the physical card number is entered into the system. If no physical card number is specified in the enrollment request, the system allocates a digital card number from the digital card pool.

The Enroll User request (CUX API) can include a loyalty card ID in the physicalCard attribute, which associates a physical card with the account. If the physicalCard attribute is left blank, the card defaults to DIGITAL and the system provides the card number from the available pool. If the loyalty card ID in the request is not in the client's pool of available numbers, the API returns an error.

The API response includes the resulting card type in the cardType attribute -- PHYSICAL if a valid loyalty ID number was provided in the request.

Enrollment - issuing a digital card and associating it to an account​

When a user enrolls, the system associates a physical or digital card number with their account.

If no physical card number is specified during enrollment, the system allocates a digital card number from the digital card pool.

If the physicalCard attribute in the Enroll User request (CUX API) is left blank, the card defaults to DIGITAL and the system provides the card number from the available pool. The API response includes the resulting card type in the cardType attribute -- DIGITAL in this case.

Low allocation availability alert​

The system sends a card availability alert when the pool of legitimate card numbers -- physical or digital -- drops below a pre-set threshold.

Card numbers must be allocated from an approved set, or pool, to ensure that all cards used in the system are legitimate, valid, and acquired through an approved process.

The alert notifies the client that their pool of member card numbers will soon be insufficient to meet demand for new issuances. It gives the client enough lead time to order additional card numbers and keep their loyalty program running without interruption.

Replace existing card​

This feature replaces an existing card with an unregistered card that has no transactions on it.

When a card needs to be replaced -- for example, because it is damaged or lost -- the system replaces the existing Active card with an unused card from the pool that has no associated transactions. The new card inherits the account, and the old card is set to Cancelled.

The replacement card must come from the allocation pool associated with the client. A card can be replaced with either a physical (plastic) or digital card. The replacement card becomes a new Active card on the account, and the replaced card is cancelled. If the Multiple Active Cards feature is enabled, the new card can also be designated as the Primary card on the account.

Cards can be cancelled and replaced from the Member page. The replacement can be a physical (plastic) or digital card with a valid card number from the allocation pool.

Bulk card allocation​

This feature allocates a block of loyalty program card numbers and, if required, orders the corresponding physical cards.

Each loyalty member must receive at least one unique card number, either in physical or digital form. The system allocates these numbers to the client as a block or pool, from which the client draws as new members join the program. Card numbers outside the assigned pool for that client cannot be used by their members.

Last updated on