Point Definition Rates

Overview

Point Definition Rates define how many points a profile earns for a given transaction. Each rate is linked to a Point Definition by its handle, and can be scoped by location, region, country, time window, and JSON Logic conditions on the profile or product — allowing complex earn programs with minimal configuration.

How Point Definition Rates Work

Supported Actions

Point Definition Rates are applied by two actions:

Action	Point Type	Use Case
Create Point (`createPoint`)	Standard Point — tracks `value_initial` and `value_remaining`	Redeemable loyalty points with optional expiry
Create Tier Point (`createTierPoint`)	Tier Point — tracks a single `value`	Progress points used for tier qualification; no expiry

Both actions use the same RateResolver to find the applicable rate, and both store the resolved rate's details in the point's meta field for audit purposes.

Rate Resolution

Both CreatePoint and CreateTierPoint resolve a rate using the same algorithm:

Fetch all published, non-archived rates matching the Point Definition handle
Filter by active time window (start_time ≤ now ≤ end_time)
Filter by location, region, and country — rates with NULL values act as catch-alls
Evaluate profile_conditions against the profile context (JSON Logic)
Evaluate product_conditions against the product/transaction context (JSON Logic)
Rank remaining rates by specificity score (more specific scoping = higher priority)
Apply rate_priority to break ties (product prefers rates with product conditions; profile prefers rates with profile conditions)
Return the highest-ranked matching rate

Rate resolution is opt-in. It only runs when check_rate = true is passed to the action.

Specificity Scoring

When multiple rates match, the most specific one wins. Specificity is calculated as:

Matched field	Score
`location_id` matches	+1
`region_id` matches	+1
`country_iso_2` matches	+1
`code` matches	+1

A rate with all four fields set outranks a catch-all rate with none set.

Point Calculation

Create Point:

points = round(round(base_amount) × rate)

Falls back to rate = 1 if no rate is resolved and no direct rate argument is provided.

Create Tier Point:

points = round(base_amount × rate)

Falls back to the raw base amount (no multiplier applied) if no rate is resolved. Does not support a direct rate argument override.

Example	Base Amount	Rate	Points Earned
Standard earn	$100	1.0	100
Half earn	$100	0.5	50
Double earn	$100	2.0	200
No rate resolved (Tier Point)	$100	—	100

Point Issuance (Pending Period)

Points are not always immediately active. The issue_period and issue_period_type fields on the rate control when a point transitions from pending to active. This applies to both CreatePoint and CreateTierPoint when accrued_at is provided.

`issue_period_type`	Behaviour
`hours`	Active after N hours
`days`	Active after N days (end of day)
`weeks`	Active after N weeks (end of day)
`months`	Active after N months (end of day)
`years`	Active after N years (end of day)
`absolute_date`	Active on a fixed date set in `issue_absolute_expiry`
`absolute_week`	Active on the Nth weekday, N weeks from earn
`absolute_month`	Active on the Nth day of the month, N months from earn

Example: issue_period = 30, issue_period_type = days — points become spendable 30 days after the transaction.

If no accrued_at is provided, the point is issued immediately (issued_at = now).

Configuring a Point Definition Rate

Prerequisites

A Point Definition must already exist. The rate's handle is inherited from the definition you select.
The Point Definition must be referenced in a CreatePoint or CreateTierPoint action on a trigger reaction, with check_rate = true enabled on the action.

Steps

Navigate to Configuration → Rates
Select the Point Definition tab
Click Add rate
Fill in the form:

Rate Details

Field	Required	Description
Name	Yes	Display label for this rate
Point Definition	No	Select the definition — automatically sets the rate handle
Rate	Yes	Earn multiplier, e.g. `0.5` = half a point per dollar
Region	No	Limit this rate to a specific region
Country	No	Limit to a country within the selected region
Location	No	Limit to a specific store or location
Code	No	Optional code for additional scoping
Published	No	Must be toggled on for the rate to be active
Archived	No	Toggle on to soft-delete the rate

Configuration

Field	Required	Description
Start Time	No	Rate becomes active at this datetime
End Time	No	Rate expires at this datetime
Issued Period	No	Number of periods before points are issued (e.g. `30`)
Issued Period Type	No	Unit for the period: `Days`, `Weeks`, `Months`, etc.
Absolute Value	Conditional	Required when period type is `Absolute Date`, `Absolute Week`, or `Absolute Month`
Profile Conditions	No	JSON Logic evaluated against the profile — rate only applies if conditions pass
Product Conditions	No	JSON Logic evaluated against the transaction/product — rate only applies if conditions pass
Earn Instructions	No	Human-readable description of earn rules
Internal Notes	No	Internal notes, not visible to profiles

Click Save

Conditions Example

Profile Conditions — award double points only for Gold tier members:

{ "==": [{ "var": "tier.handle" }, "gold"] }

Product Conditions — award points only for transactions in a specific category:

{ "==": [{ "var": "sku" }, "s100001"] }

Rates with no conditions apply unconditionally. Rates with conditions require the corresponding context to be passed by the triggering action.

{ "==": [{ "var": "sku" }, "s100001"] }

Rates with no conditions apply unconditionally. Rates with conditions require the corresponding context to be passed by the triggering action.