# Loyalty notifications

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

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

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

Depending on the [notification type](#notification-types), 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](/docs/product/applications/application-notifications/overview.md).

## 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][create] and [manage][manage] notifications of the following types:

### <Earned className="icon"/> Added/deducted points <NotificationCardTag tag="Real-time" /> {#added-deducted-points}

<Button variant="primary" size="l" href="/outbound-notifications#tag/Loyalty-notifications/webhook/addedDeductedPointsNotification">
  Notification schema
</Button>

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][importing-loyalty-points].

This notification type is available in both [profile-based][profile-based] and
[card-based][card-based] loyalty programs. You can create only one notification per
loyalty program.

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.

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 className="icon"/> Pending points <NotificationCardTag tag="Scheduled" /> {#pending-points}

<Button variant="primary" size="l" href="/outbound-notifications#tag/Loyalty-notifications/webhook/pendingActivePointsNotification">
  Notification schema
</Button>

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][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 profileNumber of points is greater than zero | Up to 2000 transactions per request. |

:::note
The timestamps in the payload refer to the
[time zone](/docs/product/loyalty-programs/profile-based/create-pb-programs.md) of the
loyalty program. The schedule itself, however, is always based on UTC.
:::

#### 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&nbsp;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**.

### <Expired className="icon"/> Expiring points <NotificationCardTag tag="Scheduled" /> {#expiring-points}

<Button variant="primary" size="l" href="/outbound-notifications#tag/Loyalty-notifications/webhook/expiringPointsNotification">
  Notification schema
</Button>

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 dateExpiration date is <code>today + scheduled days</code> (UTC)Assigned to an active customer profile or an active cardAmount of points is greater than zero | Up to 2000 transactions per request. |

This notification type is available in both [profile-based][profile-based] and
[card-based][card-based] loyalty programs. You can create only one notification per
loyalty program.

:::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. The
  schedule itself, however, is always based on UTC. See the [example](#example) for the
  <Pending className="icon"/> **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 inRequest | 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**                  | Points expire on the scheduled date | Expiration date is `today + 7 days`        |
| 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**.

### <Tier className="icon"/> Tier-related changes <NotificationCardTag tag="Real-time" /> <NotificationCardTag tag="Scheduled" /> {#tier-changes}

#### <Tier className="icon"/> Tier upgrade <NotificationCardTag tag="Real-time" /> {#tier-upgrade}

<Button variant="primary" size="l" href="/outbound-notifications#tag/Loyalty-notifications/webhook/tierUpgradeNotification">
  Notification schema
</Button>

Be notified of upgrades to loyalty tiers in real time for loyalty programs where the
loyalty tiers are defined. Tier upgrades resulting from
[imported loyalty points][importing-loyalty-points] do not trigger this notification.

Requests are sent every 10 minutes.

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

#### <Tier className="icon"/> Tier downgrade <NotificationCardTag tag="Real-time" /> {#tier-downgrade}

<Button variant="primary" size="l" href="/outbound-notifications#tag/Loyalty-notifications/webhook/tierDowngradeNotification">
  Notification schema
</Button>

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][profile-based] loyalty programs.
- The profile-based loyalty program must be set to
  [scheduled tier downgrade](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md#scheduled-tier-downgrade)
  with a
  [relative expiration date](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md#expiration-type).
- With scheduled tier downgrades, a customer's loyalty points may place them in a lower
  tier before the scheduled downgrade date. However, this notification is only triggered
  on the scheduled downgrade date, not when the points balance changes.
:::

Requests are sent every 10 minutes.

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

#### <Tier className="icon"/> Upcoming tier downgrade <NotificationCardTag tag="Scheduled" /> {#upcoming-tier-downgrade}

<Button variant="primary" size="l" href="/outbound-notifications#tag/Loyalty-notifications/webhook/tierWillDowngradeNotification">
  Notification schema
</Button>

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 dateDowngrade date is <code>today + scheduled days</code> (UTC)Triggered by a [scheduled tier downgrade](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md#scheduled-tier-downgrade)Not triggered by an [absolute tier expiration date](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md#absolute-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][profile-based] loyalty programs.
- The profile-based loyalty program must be set to
  [scheduled tier downgrade](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md#scheduled-tier-downgrade)
  with a
  [relative expiration date](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md#expiration-type).
- For more information about the `today + scheduled days` calculation, see the
  [example](#example-1) for the <Expired className="icon"/> **Expiring points**
  notification.
- The timestamps in the payload refer to the time zone of the loyalty program. The
  schedule itself, however, is always based on UTC. See the [example](#example) for the
  <Pending className="icon"/> **Pending points** notification.
- Pending point balances are not considered when evaluating upcoming tier
  downgrades.
:::

## Request logging and retry policy

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

[Progressively delayed][exp backoff] 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.

[exp backoff]: https://cloud.google.com/pubsub/docs/subscription-retry-policy#exponential_backoff

## Related pages

- [Webhooks](/docs/product/account/dev-tools/manage-webhooks.md)
- [Notification schemas][specs]
- [Application notifications](/docs/product/applications/application-notifications/overview.md)
- [Display notification logs][logs]

[card-based]: /docs/product/loyalty-programs/card-based/card-based-overview.md
[create]: /docs/product/loyalty-programs/loyalty-notifications/create-loyalty-notifications.md
[importing-loyalty-points]: /docs/product/loyalty-programs/profile-based/manage-pb-lp-data.md#import-loyalty-points
[logs]: /docs/product/account/logs/notification-logs.md
[manage]: /docs/product/loyalty-programs/loyalty-notifications/manage-loyalty-notifications.md
[profile-based]: /docs/product/loyalty-programs/profile-based/profile-based-overview.md
[specs]: /outbound-notifications#tag/Loyalty-notifications
[webhooks]: /docs/product/account/dev-tools/manage-webhooks.md