Retrieve Loyalty Program

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

Overview

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:

Retrieve a loyalty program
List loyalty programs (deprecated)

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.

Link to section

LoyaltyProgram object

The following is an example LoyaltyProgram object:

{
  "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
`status`	The 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_ids`	The IDs of the participating locations in the loyalty program.
`accrual_rules`	The 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_policy`	The 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.
`terminology`	The terminology used to represent points. For example, Point or Points and Star or Stars.
`reward_tiers`	Contains 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. 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 aren't 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):

...
"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 don't 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:

...
"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:

...
"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:

...
"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
Retrieve a loyalty program using the main keyword.
Retrieve loyalty program
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:

{
  "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.

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "detail": "Merchant does not have a loyalty program",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

Link to section

ListLoyaltyPrograms (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

The following is an example ListLoyaltyPrograms response:

{
  "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.

{}

Link to section

Docs

Retrieve a Loyalty Program

On this page

Overview

Note

LoyaltyProgram object

Accrual rules

Note

VISIT accrual rules

SPEND accrual rules

ITEM_VARIATION accrual rules

CATEGORY accrual rules

Retrieve a loyalty program

Note

ListLoyaltyPrograms (deprecated)

Note

See also

On this page