Loyalty notifications

Loyalty notifications allow you to be informed of the status of the loyalty points and tiers of your loyalty program.

In a similar way to webhooks, notifications send requests to a URL of your choice with a predefined payload. To view the payload content, see the notification schemas.

Depending on the notification type, the following are possible:

• Requests are sent either in real time after a qualifying loyalty event occurs or based on a schedule before it occurs.
• You can configure the request payload size. A larger payload means fewer requests are sent, optimizing the use of hardware resources.

To learn about notifications for Applications, see Application notifications.

Notification types

A notification type represents a qualifying loyalty program-related event for which you can create a notification and receive requests, for example, loyalty points that are expiring soon.

You can create and manage notifications of the following types:

Added/deducted points Real-time

Notification schema

Be notified of changes to the points balance of your loyalty programs in real time, whether they happen through the Campaign Manager, Management API, or the Rule Engine. However, this does not include imported loyalty points.

You can create only one notification of this type in profile-based and card-based loyalty programs.

Requests are sent immediately after the points balance changes.

With current balance

Choose Added/deducted points with current balance to receive an optimized request payload for notification triggers made by the Rule Engine.

In the payload, Actions lists all additions and deductions within a closed session, with CurrentPoints showing the resulting balance. Each distinct set of loyalty program ID, subledger ID, and customer profile ID triggers a single notification request.

Pending points Scheduled

Notification schema

Be notified of pending points in your loyalty program that are about to become active.

You can create one or more notifications of this type in profile-based loyalty programs.

Schedule	Action	Payload size
Daily at 00:00 UTC	Retrieves point transactions that meet all of the following criteria: Start date is the current calendar day (UTC) Assigned to an active customer profile Number of points is greater than zero	Up to 2000 transactions per request.

Example

You want to notify customers of pending points that are becoming active soon. You have set the reference time zone of your loyalty program to America/New_York (UTC-4).

Let's assume the current time is July 14, 20:00 UTC-4, which is July 15, 00:00 UTC. This means that today is July 15.

Talon.One checks the following point transactions:

Points	Start date (UTC-4)	Start date (UTC)	Included in Request	Reason	Calculation
10	July 14, 09:20	July 14, 13:20	No	Points are already active	Start date is before today
30	July 14, 21:00	July 15, 01:00	Yes	Points become active today	Start date is today
80	July 15, 19:59	July 15, 23:59	Yes	Points become active today	Start date is today
20	July 15, 20:00	July 16, 00:00	No	Points become active later	Start date is after today

Talon.One sends a request that contains two transactions with 30 and 80 points. The timestamps in the payload refer to the time zone of the loyalty program, so they indicate July 14 and July 15.

Expiring points Scheduled

Notification schema

Be notified of expiring loyalty points through scheduled triggers. You can add up to three scheduled request triggers, each with a different alert time before points expiration.

Schedule	Action	Payload size
Daily at 00:00 UTC	Retrieves point transactions that meet all of the following criteria: Has an expiration date Expiration date is today + scheduled days (UTC) Assigned to an active customer profile or an active card Amount of points is greater than zero	Up to 2000 transactions per request.

note

• Talon.One sums points from transactions in the request payload if all of their following attributes are identical:
  • Customer profile ID (for profile-based loyalty programs) or card ID (for card-based loyalty programs)
  • Loyalty program ID
  • Loyalty subledger ID (if applicable)
• Transactions from profile-based and card-based loyalty programs are always handled separately. If you have both types of loyalty programs, and both have expiring points, Talon.One sends two separate requests, one for each type.
• The timestamps in the payload refer to the time zone of the loyalty program. See the example for the Pending points notification.

Example

You want to notify customers one week before their points expire. You have added a scheduled trigger for 1 week before expiration.

Let's assume the current time is July 15, 00:00 UTC. That means that today + 7 days is July 22.

Talon.One checks the following point transactions:

Points	Expiration date (UTC)	Included in Request	Reason	Calculation
100	July 7, 09:20	No	Points have already expired	Expiration date is before today + 7 days
150	July 22, 00:00	Yes	Points expire on the scheduled date	Expiration date is today + 7 days
200	July 22, 23:59	Yes	See above	See above
50	July 23, 14:20	No	Points expire later	Expiration date is after today + 7 days

Assume these transactions have the same customer profile ID and loyalty program ID, and the loyalty program doesn't use subledgers.

Talon.One sends a request that contains the sum of the points expiring on July 22, which is 350 points.

You can create only one notification of this type in profile-based and card-based loyalty programs.

Tier-related changes Real-time Scheduled

Tier upgrade Real-time

Notification schema

Be notified of upgrades to loyalty tiers in real time for loyalty programs where the loyalty tiers are defined.

Requests are sent every 10 minutes.

When you create a notification, you can configure the payload to contain up to 2000 objects per request. You can create only one notification of this type.

Tier downgrade Real-time

Notification schema

Be notified of downgrades to loyalty tiers in real time for loyalty programs where the loyalty tiers are defined.

note

• You can create only one notification per loyalty program.
• This notification is only available in profile-based loyalty programs.
• The profile-based loyalty program must be set to scheduled tier downgrade with a relative expiration date.

Requests are sent every 10 minutes.

When you create a notification, you can configure the payload to contain up to 2000 objects per request.

Upcoming tier downgrade Scheduled

Notification schema

Be notified of upcoming downgrades to loyalty tiers. You can add up to three scheduled request triggers, each at a different alert time before the downgrade date.

Schedule	Action	Payload size
Daily at 00:00 UTC	Retrieves tier downgrades that meet all of the following criteria: Has a downgrade date Downgrade date is today + scheduled days (UTC) Triggered by a scheduled tier downgrade Not triggered by an absolute tier expiration date	Up to 2000 downgrades per request.

note

• You can create only one notification per loyalty program.
• This notification is only available in profile-based loyalty programs.
• The profile-based loyalty program must be set to scheduled tier downgrade with a relative expiration date.
• For more information about the today + scheduled days calculation, see the example for the Expiring points notification.
• The timestamps in the payload refer to the time zone of the loyalty program. See the example for the Pending points notification.

Request logging and retry policy

All notification types have a response timeout of 10 seconds. Requests that time out are logged with no response code.

Progressively delayed resend attempts are made up to 10 times or until a 2xx response is received, whichever occurs first. Resend attempts are made when a notification request cannot be sent for the following reasons:

• 5xx response codes.
• 429 Too Many Requests response code.
• There's no response at all.

Related pages

• Webhooks
• Notification schemas
• Application notifications
• Displaying notification logs