Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Loyalty API

Loyalty Program Overview

Customer loyalty programs help sellers increase repeat visits to their business. Square point-of-sale (POS) devices and Square Online Store support a Square loyalty program to help increase customer visit frequency. In addition, Square offers a Loyalty API for application developers to integrate the same loyalty program in their applications such as eCommerce websites, mobile applications, or POS solutions. This documentation focuses on using the Loyalty API.

It is a two-step process:

  1. Set up a loyalty program in the Square Seller Dashboard.

  2. Integrate your application with the Loyalty API to create loyalty accounts for buyers, add points for purchases, and redeem points for rewards.

Set up a loyalty program Permalink Get a link to this section

To set up a Square loyalty program, you need to:

  • Configure accrual rules. How buyers earn points.

  • Configure rewards tiers. Establish what rewards are available and how many loyalty points are required to redeem the rewards.

Accrual rules Permalink Get a link to this section

The Square loyalty program supports the following ways for buyers to earn points:

  • Visit-based accrual. 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."

  • Item-based accrual. Buyers earn points based on items in their cart. For example, "earn one point for each pumpkin latte" or "earn one point for any drink," where drink is an item category. These items and categories are defined in the seller's catalog.

  • Spend-based accrual. Buyers earn points based on the amount they spend. For example, "earn one point for every $2 dollars spent." When you use the Orders API to manage orders, the program uses pretax and pretip amounts as the amount spent in this calculation.

Reward tiers Permalink Get a link to this section

A reward tier defines the reward and the points that the buyer must redeem to get the reward. A loyalty program can offer multiple reward tiers. Tiered rewards allow sellers to offer more rewards for buyers who spend more, as shown in the following examples:

  • Reward tiers example 1:

    • Tier-1: Get a free coffee for 10 points.

    • Tier-2: Get a free sandwich for 15 points.

  • Reward tiers example 2:

    • Tier-1: Redeem 10 points and get 5% off the entire purchase.

    • Tier-2: Redeem 20 points and get 15% off the entire purchase.

  • Reward tiers example 3:

    • Tier-1: Redeem 10 points and get $1 off.

    • Tier-2: Redeem 20 points and get $3 off.

    • Tier-3: Redeem 30 points and get $5 off.

The Square loyalty program supports the following reward types:

reward-edit-1

The following sections explain these reward types.

Reward Type: Discount on an entire sale Permalink Get a link to this section

You can offer dollar-based or percentage-based discounts on an entire sale:

  • Dollars-based. A reward that applies X dollars off the entire sale. For example, "redeem 10 points for a $1 discount." Suppose a buyer adds a coffee for $4 and a sandwich for $6 to the shopping cart. The buyer can then redeem 10 points to get a $1 discount and pay only $9.

  • Percentage-based. A reward that applies X% off the entire sale. For example, "redeem 10 points for a 5% discount." You also have an option to limit the maximum discount to a fixed amount (such as, a $15 maximum).

Reward Type: Discount a specific item Permalink Get a link to this section

Instead of offering a discount on the entire sale, you can limit the reward to specific items in the seller's catalog.

The seller can identify one or more items that qualify for the discount. However, the discount applies to only a single item. For example, consider the reward "redeem 10 points to get a $1 discount on a coffee, cake, or sandwich." If a shopping cart has all these items, the discount applies only to one of these items. The system chooses the item to apply the discount to, in a way that maximizes the total discount for the buyer. Similarly, if the cart has two sandwiches, they get the discount for only one sandwich.

The discount can be dollar-based or percentage-based:

  • Dollars-based. A reward that applies X dollars off a qualifying item or list of items. For example, "redeem 10 points for a $1 discount on a coffee or cake."

  • Percentage-based. A reward that applies X% off a qualifying item or list of items. For example, "redeem 10 points for a 5% discount on a shirt or pants."

Reward Type: Discount a category Permalink Get a link to this section

You can also offer a reward on item categories in the seller's catalog. Suppose you create a drink category in the seller's catalog and list various items in the category (such as tea, coffee, and hot chocolate). You can then offer a discount for items in the drink category.

The discount can be dollar-based or percentage-based:

  • Dollars-based. A reward that applies X dollars off a qualifying category or list of categories. For example, "redeem 10 points for a $1 discount on a drink." If you have multiple drinks in your cart, the discount applies to only one item.

  • Percentage-based. A reward that applies X% off a qualifying category or list of categories. For example, "redeem 10 points for a 5% discount on a drink."

Reward Type: Redeem a free item Permalink Get a link to this section

You can offer a free item. For example, "redeem 10 points to get a free coffee." The coffee might not be in the shopping cart. You can create a custom UI experience to offer a free coffee even if the coffee item is not in the cart. But a reward that offers a free item does not automatically add the item to the order.

Related topics Permalink Get a link to this section