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_rulesContains one or more 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. Can include one or more accrual rules, which define type-specific data in the category_data field.
 •    ITEM_VARIATION. Can include one or more accrual rules, which define type-specific data in the item_variation_data field.
 •    SPEND. Can include one accrual rule, which defines type-specific data in the spend_data field.
 •    VISIT. Can include one accrual rule, which defines type-specific data in the visit_data field.

CATEGORY, ITEM_VARIATION, and SPEND accrual rules integrate with the Catalog API. For more information, see Integration with the Catalog API.

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
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: 2022-09-21' \
  -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: 2022-09-21' \
  -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: 2022-09-21' \
  -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