Learn about the LoyaltyProgram object and how to use the Square Loyalty API to retrieve a loyalty program.
Loyalty API

Retrieve a Loyalty Program

After Square sellers subscribe to Square Loyalty and set up their loyalty program, you can use the Loyalty API to get information about the program, such as the accrual rules and reward tiers.

The Loyalty API supports the following operations for working with loyalty programs:

Note

The Loyalty API cannot be used to create or update loyalty programs. For information about how sellers set up accrual rules and reward tiers for their loyalty program, see Loyalty Program Overview.

Link to section
LoyaltyProgram object

The following is an example LoyaltyProgram object:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
{
  "id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
  "status": "ACTIVE",
  "reward_tiers": [
    {
      "id": "7b897fee-572a-4516-a3d3-47676931e4f3",
      "points": 15,
      "name": "10% off entire sale",
      "definition": {
        "scope": "ORDER",
        "discount_type": "FIXED_PERCENTAGE",
        "percentage_discount": "10"
      },
      "created_at": "2020-12-16T17:39:54Z",
      "pricing_rule_reference": {
        "object_id": "ESNLTB2A77HXVKRBM",
        "catalog_version": "564027IS7PT6"
      }
    },
    {
      "id": "46c2716e-f559-4b75-c015-764897e3c4ae0",
      "points": 30,
      "name": "25% off entire sale",
      "definition": {
        "scope": "ORDER",
        "discount_type": "FIXED_PERCENTAGE",
        "percentage_discount": "25"
      },
      "created_at": "2020-12-16T17:47:22Z",
      "pricing_rule_reference": {
        "object_id": "GR4C4RSNLFBU2GMWT",
        "catalog_version": "738021351929"
      }
    }
  ],
  "terminology": {
    "one": "Point",
    "other": "Points"
  },
  "location_ids": [
    "S8GWD5R9QB376"
  ],
  "created_at": "2020-12-16T23:35:41Z",
  "updated_at": "2020-12-20T02:00:02Z",
  "accrual_rules": [
    {
      "accrual_type": "SPEND",
      "points": 1,
      "spend_data": {
        "amount_money": {
          "amount": 200,
          "currency": "USD"
        },
        "excluded_category_ids": [
          "7ZERJKO5PVYXCVUHV2JCZ2UG",
          "FQKAOJE5C4FIMF5A2URMLW6V"
        ],
        "excluded_item_variation_ids": [
          "CBZXBUVVTYUBZGQO44RHMR6B",
          "EDILT24Z2NISEXDKGY6HP7XV"
        ],
        "tax_mode": "BEFORE_TAX"
      }
    }
  ]
}

This example loyalty program allows buyers to accrue one point for every $2 spent on qualifying items and offers two percentage-based reward tiers.

The following fields represent key attributes of a loyalty program:

Field
Description
statusThe status of the loyalty program, which is determined by the status of the seller's Square Loyalty subscription. All write operations in the Loyalty API require that the loyalty program is ACTIVE.
location_idsThe IDs of the participating locations in the loyalty program.
accrual_rulesThe accrual rules that define how buyers can earn points from the base loyalty program. A loyalty program can contain a single type of accrual rule: CATEGORY, ITEM_VARIATION, SPEND, or VISIT. For more information, see Accrual rules.

Buyers can also earn additional points from loyalty promotions associated with a loyalty program.
expiration_policyThe number of months before points expire, in P[n]M RFC 3339 duration format. For example, a value of P12M represents a duration of 12 months. This field is present only if the loyalty program has an expiration policy. For information about how sellers configure an expiration policy, see Add Points Expiration Date in Create a Loyalty Program with Square.

Loyalty accounts that have expiring points include an expiring_point_deadlines field.
terminologyThe terminology used to represent points. For example, Point or Points and Star or Stars.
reward_tiersContains one or more reward tiers that define how buyers can redeem points for rewards.

To get information about the reward tier discount, call the RetrieveCatalogObject endpoint using the object_id and catalog_version from the pricing_rule_reference field. Make sure to set include_related_objects to true. For more information, see Integration with the Catalog API and Getting discount details for a reward tier.

Note
Loyalty reward tiers currently include the deprecated definition field, which is replaced by the pricing_rule_reference field. When possible, you should use pricing_rule_reference.

A loyalty program can have up to 10 ACTIVE and SCHEDULED loyalty promotions that enable buyers to earn extra points. Square provides specific endpoints for working with loyalty promotions; they are not visible or accessible directly from the LoyaltyProgram object. For more information, see Manage Loyalty Promotions.

Link to section
Accrual rules

Accrual rules define how buyers can earn points from the base loyalty program. The type of accrual rule used by a loyalty program determines the program type.

The accrual rules for a loyalty program are defined in the accrual_rules field. Accrual rules are represented by a LoyaltyProgramAccrualRule object. Each accrual rule specifies the rule type, number of points that buyers earn from the rule, and type-specific data.

Loyalty programs use the following rule types:

Note

CATEGORY, ITEM_VARIATION, and SPEND accrual rules integrate with the Catalog API. To get information about the catalog objects used in accrual rules, you can call BatchRetrieveCatalogObjects in the Catalog API.

Link to section
VISIT accrual rules

VISIT accrual rules are used by Visit-based program types. Buyers earn points for every purchase, with an optional minimum spend requirement. For example, "Earn one point for each visit, with a $5 minimum purchase required". This program type defines one VISIT accrual rule.

VISIT accrual rules define type-specific data in the visit_data field. This rule type can optionally specify minimum_amount_money, which defines the minimum purchase amount required during the visit to quality for points. If minimum_amount_money is specified, the tax_mode field indicates how taxes should be treated when calculating the purchase amount.

The following example accrual rule enables buyers to earn 1 point for each visit with a $5.00 minimum purchase (not including tax):

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
...
"accrual_rules": [
  {
    "accrual_type": "VISIT",
    "points": 1,
    "visit_data": {
      "minimum_amount_money": {
        "amount_money": {
          "amount": 500,
          "currency": "USD"
        }
      },
      "tax_mode": "BEFORE_TAX"
    }
  }
],
...

Link to section
SPEND accrual rules

SPEND accrual rules are used by Amount-spent program types. Buyers earn points based on the amount they spend. For example, "Earn one point for every $2 dollars spent". This program type defines one SPEND accrual rule.

SPEND accrual rules define type-specific data in the spend_data field. The tax_mode field indicates how taxes should be treated when calculating the purchase amount. This rule type can optionally specify excluded_category_ids and excluded_item_variation_ids, which contain the IDs of any CATEGORY and ITEM_VARIATION catalog objects that do not qualify for points accrual.

The following example accrual rule enables buyers to earn 5 points for purchases of $25.00 or more, excluding the specified items:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
...
"accrual_rules": [
  {
    "accrual_type": "SPEND",
    "points": 5,
    "spend_data": {
      "amount_money": {
        "amount": 2500,
        "currency": "USD"
      },
      "excluded_category_ids": [
        "FQKAOJE5C4FIMF5A2URMLW6V"
      ],
      "excluded_item_variation_ids": [
        "CBZXBUVVTYUBZGQO44RHMR6B",
        "EDILT24Z2NISEXDKGY6HP7XV"
      ],
      "tax_mode": "BEFORE_TAX"
    }
  }
],
...

Link to section
ITEM_VARIATION accrual rules

ITEM_VARIATION accrual rules are used by Item-based program types. Buyers earn points when they purchase specific items or services. For example, "Earn one point for each pumpkin latte purchased", where pumpkin latte is an item in the seller's catalog. This program type defines one or more ITEM_VARIATION accrual rules.

ITEM_VARIATION accrual rules define type-specific data in the item_variation_data field. This rule type specifies an item_variation_id, which references the ITEM_VARIATION catalog object that qualifies for points accrual.

The following example accrual rules enable buyers to earn 1 or 2 points by purchasing the specified items:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
...
"accrual_rules": [
  {
    "accrual_type": "ITEM_VARIATION",
    "points": 1,
    "item_variation_data": {
      "item_variation_id": "CBZXBUVVTYUBZGQO44RHMR6B"
    }
  },
  {
    "accrual_type": "ITEM_VARIATION",
    "points": 2,
    "item_variation_data": {
      "item_variation_id": "EDILT24Z2NISEXDKGY6HP7XV"
    }
  }
],
...

Link to section
CATEGORY accrual rules

CATEGORY accrual rules are used by Category-based program types. Buyers earn points when they purchase items or services from specific categories. For example, "Earn one point for any drink purchased", where drink is an item category in the seller's catalog. This program type defines one or more CATEGORY accrual rules.

CATEGORY accrual rules define type-specific data in the category_data field. This rule type specifies a category_id, which references the CATEGORY catalog object that qualifies for points accrual.

The following example accrual rules enable buyers to earn 1 or 3 points by purchasing items from the specified categories:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
...
"accrual_rules": [
  {
    "accrual_type": "CATEGORY",
    "points": 1,
    "category_data": {
      "category_id": "7ZERJKO5PVYXCVUHV2JCZ2UG"
    }
  },
  {
    "accrual_type": "CATEGORY",
    "points": 3,
    "category_data": {
      "category_id": "FQKAOJE5C4FIMF5A2URMLW6V"
    }
  }
],
...

Link to section
Retrieve a loyalty program

Call RetrieveLoyaltyProgram to get a loyalty program by the program ID or using the main keyword. A seller account can contain only one loyalty program, so either value can be used to retrieve the loyalty program that belongs to the seller.

  • Retrieve a loyalty program by the program ID.

    Retrieve Loyalty Program
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/loyalty/programs/{program_id} \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
    Try in API Explorer

  • Retrieve a loyalty program using the main keyword.

    Retrieve Loyalty Program
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/loyalty/programs/main \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
    Try in API Explorer

    Note

    Only the RetrieveLoyaltyProgram endpoint supports using the main keyword in place of the program ID. For example, you cannot use main to call CalculateLoyaltyPoints.

The following is an example RetrieveLoyaltyProgram response:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
  • 68
{
  "program": {
    "id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
    "status": "ACTIVE",
    "reward_tiers": [
      {
        "id": "7b897fee-572a-4516-a3d3-47676931e4f3",
        "points": 15,
        "name": "10% off entire sale",
        "definition": {
          "scope": "ORDER",
          "discount_type": "FIXED_PERCENTAGE",
          "percentage_discount": "10"
        },
        "created_at": "2020-12-16T17:39:54Z",
        "pricing_rule_reference": {
          "object_id": "ESNLTB2A77HXVKRBM",
          "catalog_version": "564027IS7PT6"
        }
      },
      {
        "id": "46c2716e-f559-4b75-c015-764897e3c4ae0",
        "points": 30,
        "name": "25% off entire sale",
        "definition": {
          "scope": "ORDER",
          "discount_type": "FIXED_PERCENTAGE",
          "percentage_discount": "25"
        },
        "created_at": "2020-12-16T17:47:22Z",
        "pricing_rule_reference": {
          "object_id": "GR4C4RSNLFBU2GMWT",
          "catalog_version": "738021351929"
        }
      }
    ],
    "terminology": {
      "one": "Point",
      "other": "Points"
    },
    "location_ids": [
      "S8GWD5R9QB376"
    ],
    "created_at": "2020-12-16T23:35:41Z",
    "updated_at": "2020-12-20T02:00:02Z",
    "accrual_rules": [
      {
        "accrual_type": "SPEND",
        "points": 1,
        "spend_data": {
          "amount_money": {
            "amount": 200,
            "currency": "USD"
          },
          "excluded_category_ids": [
            "7ZERJKO5PVYXCVUHV2JCZ2UG",
            "FQKAOJE5C4FIMF5A2URMLW6V"
          ],
          "excluded_item_variation_ids": [
            "CBZXBUVVTYUBZGQO44RHMR6B",
            "EDILT24Z2NISEXDKGY6HP7XV"
          ],
          "tax_mode": "BEFORE_TAX"
        }
      }
    ]
  }
}

Square returns a 404 NOT_FOUND error if the seller has never subscribed to Square Loyalty.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
{
  "errors": [
    {
      "code": "NOT_FOUND",
      "detail": "Merchant does not have a loyalty program",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

Link to section
List loyalty programs (deprecated)

Call ListLoyaltyPrograms to list the loyalty programs in a seller's account. A seller account can contain one loyalty program, so only one loyalty program is returned in the list.

Note

The ListLoyaltyPrograms endpoint is deprecated. When possible, you should use the RetrieveLoyaltyProgram endpoint with the main keyword instead. RetrieveLoyaltyProgram and ListLoyaltyPrograms provide the same functionality because a seller account can contain only one loyalty program. For more information, see Migration notes.

List Loyalty Programs
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/loyalty/programs \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
Try in API Explorer

The following is an example ListLoyaltyPrograms response:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
{
  "programs": [
    {
      "id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "status": "ACTIVE",
      "reward_tiers": [
        {
          "id": "7b897fee-572a-4516-a3d3-47676931e4f3",
          "points": 15,
          "name": "10% off entire sale",
          "definition": {
            "scope": "ORDER",
            "discount_type": "FIXED_PERCENTAGE",
            "percentage_discount": "10"
          },
          "created_at": "2020-12-16T17:39:54Z",
          "pricing_rule_reference": {
            "object_id": "ESNLTB2A77HXVKRBM",
            "catalog_version": "564027IS7PT6"
          }
        },
        {
          "id": "46c2716e-f559-4b75-c015-764897e3c4ae0",
          "points": 30,
          "name": "25% off entire sale",
          "definition": {
            "scope": "ORDER",
            "discount_type": "FIXED_PERCENTAGE",
            "percentage_discount": "25"
          },
          "created_at": "2020-12-16T17:47:22Z",
          "pricing_rule_reference": {
            "object_id": "GR4C4RSNLFBU2GMWT",
            "catalog_version": "738021351929"
          }
        }
      ],
      "terminology": {
        "one": "Point",
        "other": "Points"
      },
      "location_ids": [
        "S8GWD5R9QB376"
      ],
      "created_at": "2020-12-16T23:35:41Z",
      "updated_at": "2020-12-20T02:00:02Z",
      "accrual_rules": [
        {
          "accrual_type": "SPEND",
          "points": 1,
          "spend_amount_money": {
            "amount": 200,
            "currency": "USD"
          },
          "excluded_category_ids": [
            "7ZERJKO5PVYXCVUHV2JCZ2UG",
            "FQKAOJE5C4FIMF5A2URMLW6V"
          ],
          "excluded_item_variation_ids": [
            "CBZXBUVVTYUBZGQO44RHMR6B",
            "EDILT24Z2NISEXDKGY6HP7XV"
          ]
        }
      ]
    }
  ]
}

Square returns an empty object if the seller has never subscribed to Square Loyalty.

  • 1
{}

Link to section
Related topics

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

On this page