Points Expiration

Every unit of loyalty balance goes through a lifecycle: awarded → available → spent → expired. Loyalty rules can be configured with both an activation delay and an expiration period.

Balance Fields

Field	Description
score	Total accumulated balance, including amounts not yet active
score_available	Active balance that can be spent today

Only score_available can be used for cashback or rewards. Balance in the activation delay period is included in score but not yet spendable.

Activation Delay

Points are not always available immediately after being earned.

Setting	Effect
0 days	Points are immediately available
N days	Points become available N days after being earned
N months (standard)	Points become available N months after being earned
N months + "Beginning of month"	Points become available on the 1st of the Nth month

Expiration Models

Relative Period

Expiration counted from when the points were earned (or activated).

Setting	Effect
N days	Points expire N days after the reference date
N months (standard)	Points expire N months after the reference date
N months + "Natural month"	Expiration extends to the last day of the month

Fixed Period

Expiration happens at a fixed calendar date, regardless of when points were earned.

Option	Expiration date
End of calendar month	Last day of the month earned
End of calendar quarter	March 31, June 30, September 30, or December 31
End of calendar semester	June 30 or December 31
End of calendar year	December 31

Negative Balances

If a customer returns a purchase after spending the earned points, the system subtracts the reversed points from the current balance — creating a temporary negative balance. Future earned points compensate the deficit first before becoming available.

How It Works

Each points campaign has two optional lifecycle settings applied to the points it awards:

1. Activation delay — points are in score but not score_available until the delay passes.
2. Expiration — once active, points have a finite lifetime before they are removed from score_available.

Both are evaluated continuously; expired points are swept in a nightly batch job.

Configuration

Configure activation delay and expiration in Loyalty and Promotional engine → Points & Wallet → [Rule] → Lifecycle:

Setting	Description
Activation delay	0 days, N days, N months, or N months + beginning of month
Expiration model	Relative period or fixed calendar period (see table above)
Expiration notification	Optionally trigger a communication N days before expiration

Configuration field names (API)

When reading or creating campaigns via GET /points or POST /points, the activation and expiration settings map to these JSON fields:

Setting	Field	Values
Activation delay amount	activation_delay	Integer
Activation delay unit	activation_delay_unit	"days", "months"
Fixed period activation	activation_period_type	"fixed"
Expiration amount	availability_duration	Integer
Expiration unit	availability_duration_unit	"days", "months"
Extend to end of natural month	availability_duration_natural	true / false

FIFO spend order

When a customer redeems points as cashback, the system always spends the balance with the earliest expiry date first. This maximizes the likelihood that older points are used before they expire.

Negative balance

If a customer earns points and then returns the purchase:

1. Points earned are subtracted from score and score_available.
2. If the customer already spent those points (on a different purchase), balance goes negative.
3. Future earnings first compensate the deficit before becoming spendable.

Example sequence:

1. Purchase A → earn 200 pts → score_available: 200
2. Spend 200 pts as cashback on Purchase B → score_available: 0
3. Return Purchase A → subtract 200 pts → score_available: -200
4. Next earn of 300 pts → score_available: 100 (offset applied first)

See Returns for the full return flow.