LoyaltyProgram

When updating, already existing fields omitted from the payload will generally not be deleted unless otherwise specified.

accrual_point_rounding_mode
Type: stringenum
required

Determines how calculated earned points will be rounded. When rounding to nearest, X.5 will be rounded up.

Example: Earning 10 points/dollar on $3.51 = 35.1 points. Rounding down or nearest would yield 35 points, while up would yield 36.

This field defaults to down when omitted.
values
- down
- up
- nearest
accrual_subtotal_rounding_mode
Type: stringenum
required

Determines if/how eligible subtotals (total of item values less discounts) will be rounded to whole dollar values before calculating earned points. When rounding to nearest, $X.50 will be rounded up.

Example: Earning 10 points/dollar on $3.51. Rounding up or nearest would result in $4.00 or 40 points. Rounding down would yield $3.00 or 30 points. none would result in 35.1 points, rounded according to accrual_point_rounding_mode.

This field defaults to none when omitted.
values
- none
- down
- up
- nearest
name
Type: string
required
created_at
Type: stringFormat: date-time
read-only

the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z
description
Type: string
id
Type: integer
read-only

Integer numbers.
max_points_per_transaction
Type: integer
min:
0

The maximum number of points that can be earned on a transaction. If this field is null or omitted, there is no limit.
point_expiration_date_buffer_type
Type: stringenum
Determines if and how calculated point expiration dates (after applying point_expiration_days) will be adjusted to align with a specific calendar boundary. When set to first_of_month, the computed expiration date will be moved forward to the first day of the following month. When set to none, the expiration date will remain exactly as calculated with no additional adjustment.

Example: If point_expiration_days results in an expiration date of March 18:
- none would keep the expiration date as March 18.
- first_of_month would adjust the expiration date to April 1.
This field defaults to none when omitted.
values
- none
- first_of_month
point_expiration_days
Type: integer
min:
0

How many days after they are earned that points will expire, or 0 if they should never expire.
point_expiration_time
Type: string
An optional timestamp in the format of HH:00 (00:00 to 23:00) that will control the time of day at which points will expire after the expiration date is determined.
- required if point_expiration_time_zone is set
- when null or omitted, points will expire at the same UTC time of day
- any other value will be documented/interpreted as a local time
point_expiration_time_zone
Type: string
An optional string time zone to represent the locale of any explicit point_expiration_time
- required if point_expiration_time is set
retro_claim_days
Type: integer

How many days transactions can be retro claimed after they occur. If this field is null or omitted, there is no time limitation.
retro_claim_limitation_days
Type: integer
min:
0
Apply limitations to retro claims made over a certain number of days (e.g. if using a limitation type of "points" and this is set to 30, an enrollment may only earn 30 points from retro claims over a period of 30 days).
- All retro claims will count toward limitations when this field is omitted or null.
- Limited activity (retro claiming, point earn, etc.) will be prevented when set to 0.
retro_claim_limitation_max_points
Type: integer
min:
0
Determines how many points can be earned through retro claims within the defined limitation period.
- This limitation will not be applied if field is omitted or null.
- This field only applies when using the "points" limitation type.
retro_claim_limitation_total_claims
Type: integer
min:
0
Determines how many transactions can be retro claimed within the defined limitation period.
- This limitation will not be applied if field is omitted or null.
- This field only applies when using the "claims" limitation type.
retro_claim_limitation_total_claims_per_trans_date
Type: integer
min:
0
Determines how many transactions placed on the same date can be retro claimed within the defined limitation period.
- This limitation will not be applied if field is omitted or null.
- This field only applies when using the "claims" limitation type.
retro_claim_limitation_type
enum
Determines what should be limited when retro claiming eligible transactions. Unrelated limitations such as max_points_per_transaction and retro_claim_days still apply.
- none - no limitation (default)
- points - limit points earned through retro claims. See related settings retro_claim_limitation_days & retro_claim_limitation_max_points for more details.
- claims - limit number of retro claims allowed. See related settings retro_claim_limitation_days, retro_claim_limitation_total_claims, & retro_claim_limitation_total_claims_per_trans_date for more details
values
- none
- points
- claims
status
Type: stringenum
read-only
values
- active
- suspended
- archived
tier_system_config
Type: object · LoyaltyTierSystemsConfig

Determines how optional Loyalty Enrollment Tiering will work within a Loyalty Program, specifically how point earning activity is determined as qualifying (or not) toward meeting Tier requirements, and how long Enrollments are granted access to Tiers.

Specific criteria (e.g. how many lifetime points are needed) for earning into each Tier is configured at the Tier level (see Loyalty Tier Grant Rule).
- align_renewal_with_tier_term_end
  Type: boolean
  required
  
  Enrollments are automatically evaluated for tiers whenever they earn points. By default, evaluation uses point threshold lookback windows and calculates the end of grant terms based on that evaluation date for both advancement (moving to a higher tier) and renewal (qualifying for the same or lower tier for an extended period).
  
  When this setting is true, renewal evaluations consider qualifying points as those earned during an enrollment's current "Tier Term" (see tier_term_start_time and tier_term_end_date on the Loyalty Enrollment). Renewal tier grants end a full grant term after the current Tier Term ends. "Tier Terms" typically (re)start when enrollments automatically advance tiers, end on the same date as the corresponding tier grants, and are extended a full grant term if they lapse.
  
  Example with anniversary-based renewal: An enrollment advances to "Silver" on June 1, 2025, making the end of their tier term June 1, 2026 (a 365-day grant term later). Throughout that year, renewal evaluation checks if they qualify for "Silver" based only on points earned during that time. If they do, a renewal grant is issued that ends on June 1, 2027 (365 days from their upcoming anniversary/term end). If the enrollment does not advance to "Gold" by June 1, 2026, their tier term would reset to end on June 1, 2027.
  
  Note: Advancement always uses the current date for evaluation. This setting only affects renewal behavior.
- grant_term_type
  Type: stringenum
  required
  
  determines if and if so how long an enrollment gets to remain in a tier (assuming inactivity) once they are granted access.
  
  permanent - when automatically granted access to a tier, an enrollment's access does not expire.
  
  calendar_years - when automatically granted access to a tier, an enrollment retains access for n calendar years, inclusive of the current year (e.g. if "Gold Tier" is earned in June 2024, and a program configures a term type/length of "2 calendar years", the enrollment would remain at least in "Gold Tier" through December 31st, 2025).
  
  relative_days - when automatically granted access to a tier, access is retained for the following n days.
  
  values
  permanent
  calendar_years
  relative_days
- point_threshold_length
  Type: integer
  required
  
  quantifies point_threshold_type if applicable (e.g. 2 calendar years).
- point_threshold_type
  Type: stringenum
  required
  
  determines which point values contribute toward meeting tier thresholds.
  
  total_historical - enrollments are granted access to tiers upon reaching a lifetime earned point total. Since tiers would not be based on recency or frequency of activity, programs using this setting would generally be expected to award tiers permanently (grant_term_type set to permanent).
  
  calendar_years - enrollments are granted access to tiers based on how many points they have earned over the course of the past n calendar years, inclusive of the current year.
  
  relative_days - enrollments are granted access to tiers based on how many points they have earned over the course of the past n relative days.
  
  values
  total_historical
  calendar_years
  relative_days
- enabled
  Type: boolean
  
  determines whether tiering is enabled for the program.
- grant_term_length
  Type: integer
  
  quantifies grant_term_type if applicable. If grant_term_type is permanent, this will be set to 0.
updated_at
Type: stringFormat: date-time
read-only

the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z

Examples

{
  "name": "Test Program 2",
  "description": "An example Loyalty Program",
  "default_point_accrual_rule": {
    "name": "5 points per dollar plus 10 points per visit base rule ",
    "accrual_multiplier": 0.05,
    "accrual_fixed": 10,
    "min_spend_amount": 0
  }
}