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.

LoyaltyProgram object Permalink Get a link to this section

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 purchases. Loyalty programs can contain a single type of accrual rule:
 •    CATEGORY. Can include one or more accrual rules.
 •    ITEM_VARIATION. Can include one or more accrual rules.
 •    SPEND. Can include one accrual rule.
 •    VISIT. Can include one accrual rule.

Accrual rules use the category_data, item_variation_data, spend_data, or visit_data field to define additional data for the rule type.

CATEGORY, ITEM_VARIATION, and SPEND accrual rules integrate with the Catalog API. For more information, see Integration with the Catalog API.
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.

Retrieve a loyalty program Permalink Get a link to this section

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-05-12' \
  -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-05-12' \
  -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"
    }
  ]
}

List loyalty programs (deprecated) Permalink Get a link to this section

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-05-12' \
  -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
{}

Related topics Permalink Get a link to this section

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

On this page