Reward Tier ID Changing on Editing

Questions
1

We have created a Reward Program in Loyalty.

State 1:

{
“program”: {
“id”: “fd3f86f3-c753-45d9-afee-05aa67f8b5b6”,
“status”: “ACTIVE”,
“reward_tiers”: [
{
“id”: “c5693b5c-0bd7-4aad-92db-3921bd32c74a”,
“points”: 2,
“name”: “$1.00 off entire sale”,
“definition”: {
“scope”: “ORDER”,
“discount_type”: “FIXED_AMOUNT”,
“fixed_discount_money”: {
“amount”: 100,
“currency”: “USD”
}
},
“created_at”: “2025-09-29T10:34:20Z”,
“pricing_rule_reference”: {
“object_id”: “3R7KOEZ2G2FHSRGMKPQFM4K2”,
“catalog_version”: 1759142060152
}
}
],
“terminology”: {
“one”: “Point”,
“other”: “Points”
},
“location_ids”: [
“LG5EZBAXEZCZW”,
“RTPCZEZH1ADKQ”
],
“created_at”: “2024-09-30T05:40:58Z”,
“updated_at”: “2025-09-29T10:34:20Z”,
“accrual_rules”: [
{
“accrual_type”: “SPEND”,
“points”: 1,
“spend_data”: {
“amount_money”: {
“amount”: 100,
“currency”: “USD”
},
“tax_mode”: “BEFORE_TAX”
}
}
]
}
}

Then we changed the points value on the reward tier object and saved.

State 2:

{
“program”: {
“id”: “fd3f86f3-c753-45d9-afee-05aa67f8b5b6”,
“status”: “ACTIVE”,
“reward_tiers”: [
{
“id”: “ca4fcad2-e456-4e07-85cf-2ac62e2684ed”,
“points”: 1,
“name”: “$1.00 off entire sale”,
“definition”: {
“scope”: “ORDER”,
“discount_type”: “FIXED_AMOUNT”,
“fixed_discount_money”: {
“amount”: 100,
“currency”: “USD”
}
},
“created_at”: “2025-09-29T11:04:18Z”,
“pricing_rule_reference”: {
“object_id”: “2KYTSJHCUPSPDG4BD67HNSJS”,
“catalog_version”: 1759143858869
}
}
],
“terminology”: {
“one”: “Point”,
“other”: “Points”
},
“location_ids”: [
“LG5EZBAXEZCZW”,
“RTPCZEZH1ADKQ”
],
“created_at”: “2024-09-30T05:40:58Z”,
“updated_at”: “2025-09-29T11:04:19Z”,
“accrual_rules”: [
{
“accrual_type”: “SPEND”,
“points”: 1,
“spend_data”: {
“amount_money”: {
“amount”: 100,
“currency”: “USD”
},
“tax_mode”: “BEFORE_TAX”
}
}
]
}
}

As you can see, the ID of the Reward Tier has changed. This creates a problem for us as we don’t have a way to map to the correct reward tier once a change is made.

Square-Version: 2025-05-21

How do we tackle this?

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Loyalty API
Redeem Loyalty Points for a Discount (Walkthrough 1)
Redeem Loyalty Points for a Discount (Walkthrough 2)

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

When you update a reward tier in Square’s Loyalty Program, a new reward tier ID is generated, which can indeed create challenges in mapping to the correct reward tier if you rely on the ID for tracking. Here are some strategies to tackle this issue:

  1. Use a Consistent Naming Convention: Ensure that each reward tier has a unique and descriptive name that doesn’t change even if the ID does. This way, you can use the name as a reference point to identify the reward tier.

  2. Track Changes with Webhooks: Implement webhooks to listen for loyalty.program.updated events. This will notify you whenever a loyalty program is updated, allowing you to capture the new reward tier ID and update your records accordingly.

  3. Store Historical Data: Maintain a historical record of reward tiers, including their IDs, names, and other relevant details. When a change occurs, compare the new data with your historical records to identify which reward tier has been updated.

  4. Use External Identifiers: If possible, use an external identifier or metadata that you control to map reward tiers. This could be a custom field or a reference in your system that remains constant even when the Square ID changes.

  5. Regularly Sync Data: Periodically retrieve the latest loyalty program details using the RetrieveLoyaltyProgram endpoint to ensure your system is up-to-date with the current reward tiers and their IDs.

By implementing these strategies, you can better manage changes to reward tier IDs and maintain accurate mappings in your system.

This answer was reviewed by @Bryan-Square.