TAtalon
Loyalty

Get loyalty program

[!note] Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Get the specified loyalty program.

To list all loyalty programs in your Application, use List loyalty programs.

To list the loyalty programs that a customer profile is part of, use List customer data.

get/v1/loyalty_programs/{loyaltyProgramId}

Request

Path parameters

loyaltyProgramIdinteger required

Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint.

Response

OK

idinteger required

The ID of loyalty program.

createdstring date-time required

The time this entity was created.

titlestring required

The display title for the Loyalty Program.

descriptionstring required

Description of our Loyalty Program.

subscribedApplicationsinteger[] required

A list containing the IDs of all applications that are subscribed to this Loyalty Program.

defaultValiditystring required

The default duration after which new loyalty points should expire. Can be 'unlimited' or a specific time. The time format is a number followed by one letter indicating the time unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding suffixes are also supported:

  • '_D' for rounding down. Can be used as a suffix after 'D', and signifies the start of the day.
  • '_U' for rounding up. Can be used as a suffix after 'D', 'W', and 'M', and signifies the end of the day, week, and month.
defaultPendingstring required

The default duration of the pending time after which points should be valid. Accepted values: 'immediate', 'on_action' or a specific time. The time format is a number followed by one letter indicating the time unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding suffixes are also supported:

  • '_D' for rounding down. Can be used as a suffix after 'D', and signifies the start of the day.
  • '_U' for rounding up. Can be used as a suffix after 'D', 'W', and 'M', and signifies the end of the day, week, and month.
allowSubledgerboolean required

Indicates if this program supports subledgers inside the program.

usersPerCardLimitinteger

The max amount of user profiles with whom a card can be shared. This can be set to 0 for no limit. This property is only used when cardBased is true.

sandboxboolean required

Indicates if this program is a live or sandbox program. Programs of a given type can only be connected to Applications of the same type.

programJoinPolicy'not_join' | 'points_activated' | 'points_earned'

The policy that defines when the customer joins the loyalty program.

  • not_join: The customer does not join the loyalty program but can still earn and spend loyalty points.

    Note: The customer does not have a program join date.

  • points_activated: The customer joins the loyalty program only when their earned loyalty points become active for the first time.

  • points_earned: The customer joins the loyalty program when they earn loyalty points for the first time.

tiersExpirationPolicy'tier_start_date' | 'program_join_date' | 'customer_attribute' | 'absolute_expiration'

The policy that defines how tier expiration, used to reevaluate the customer's current tier, is determined.

  • tier_start_date: The tier expiration is relative to when the customer joined the current tier.
  • program_join_date: The tier expiration is relative to when the customer joined the loyalty program.
  • customer_attribute: The tier expiration is determined by a custom customer attribute.
  • absolute_expiration: The tier is reevaluated at the start of each tier cycle. For this policy, it is required to provide a tierCycleStartDate.
tierCycleStartDatestring date-time

Timestamp at which the tier cycle starts for all customers in the loyalty program.

Note: This is only required when the tier expiration policy is set to absolute_expiration.

tiersExpireInstring

The amount of time after which the tier expires and is reevaluated.

The time format is an integer followed by one letter indicating the time unit. Examples: 30s, 40m, 1h, 5D, 7W, 10M, 15Y.

Available units:

  • s: seconds
  • m: minutes
  • h: hours
  • D: days
  • W: weeks
  • M: months
  • Y: years

You can round certain units up or down:

  • _D for rounding down days only. Signifies the start of the day.
  • _U for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.
tiersDowngradePolicy'one_down' | 'balance_based'

The policy that defines how customer tiers are downgraded in the loyalty program after tier reevaluation.

  • one_down: If the customer doesn't have enough points to stay in the current tier, they are downgraded by one tier.
  • balance_based: The customer's tier is reevaluated based on the amount of active points they have at the moment.
returnPolicy'only_pending' | 'within_balance' | 'unlimited'

The policy that defines the rollback of points in case of a partially returned, cancelled, or reopened customer session.

  • only_pending: Only pending points can be rolled back.
  • within_balance: Available active points can be rolled back if there aren't enough pending points. The active balance of the customer cannot be negative.
  • unlimited: Allows negative balance without any limit.
accountIDinteger required

The ID of the Talon.One account that owns this program.

namestring required

The internal name for the Loyalty Program. This is an immutable value.

timezonestring required

A string containing an IANA timezone descriptor.

cardBasedboolean required

Defines the type of loyalty program:

  • true: the program is a card-based.
  • false: the program is profile-based.
canUpdateTiersboolean

True if the tier definitions can be updated.

canUpdateTierExpirationPolicyboolean

True if the tier expiration policy can be updated.

canUpgradeToAdvancedTiersboolean

True if the program can be upgraded to use the tiersExpireIn and tiersDowngradePolicy properties.

canUpdateSubledgersboolean

True if the allowSubledger property can be updated in the loyalty program.

Example response

{
  "id": 139,
  "created": "2020-06-10T09:05:27.993483Z",
  "title": "Point collection",
  "description": "Customers collect 10 points per 1$ spent",
  "subscribedApplications": [
    132,
    97
  ],
  "defaultValidity": "2W_U",
  "defaultPending": "immediate",
  "usersPerCardLimit": 111,
  "sandbox": true,
  "tierCycleStartDate": "2021-09-12T10:12:42Z",
  "tiersExpireIn": "27W_U",
  "cardCodeSettings": {
    "validCharacters": [
      "A",
      "B",
      "C",
      "D",
      "E",
      "F",
      "G",
      "H",
      "I",
      "J",
      "K",
      "L",
      "M",
      "N",
      "O",
      "P",
      "Q",
      "R",
      "S",
      "T",
      "U",
      "V",
      "W",
      "X",
      "Y",
      "Z",
      "0",
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8",
      "9"
    ],
    "couponPattern": "SUMMER-####-####"
  },
  "accountID": 1,
  "name": "my_program",
  "tiers": [
    {
      "name": "Gold",
      "minPoints": 300,
      "id": 3,
      "created": "2021-06-10T09:05:27.993483Z",
      "programID": 139
    },
    {
      "name": "Silver",
      "minPoints": 200,
      "id": 2,
      "created": "2021-06-10T09:04:59.355258Z",
      "programID": 139
    },
    {
      "name": "Bronze",
      "minPoints": 100,
      "id": 1,
      "created": "2021-06-10T09:04:39.355258Z",
      "programID": 139
    }
  ],
  "timezone": "Europe/Berlin",
  "cardBased": true,
  "canUpdateTiers": true,
  "canUpdateTierExpirationPolicy": true,
  "canUpgradeToAdvancedTiers": true,
  "canUpdateSubledgers": true
}

Changes

No recorded changes to this operation across all 2 revisions of this API.