Applies to: Loyalty API
Learn about Square loyalty programs, accrual rules, and reward tiers.
Customer loyalty programs help sellers to increase repeat visits to their business by rewarding customers. Square sellers who use Square Point of Sale (POS) or Square Online can subscribe to Square Loyalty and set up a loyalty program in the Square Dashboard. For feature and pricing information, see Square Loyalty and Overview of Square Loyalty. For the list of countries where Square Loyalty is available, see International availability of Square Loyalty.
Square provides a Loyalty API that developers can use to integrate Square Loyalty into their applications. For more information, see Loyalty API.
Sellers can set up a loyalty program and subscribe to Square Loyalty from the Loyalty page in the Square Dashboard. A seller account can have one loyalty program with one or more participating locations.
When setting up a Square loyalty program in the Square Dashboard, sellers configure loyalty program settings such as accrual rules and reward tiers.
Note
The Loyalty API cannot be used to create or update a loyalty program.
To test your calls to the Loyalty API, you can subscribe to Square Loyalty in the Square Dashboard using your Sandbox test account and a test credit card that is never charged. For steps that show to subscribe and set up a free loyalty program in the Sandbox environment, follow step 1 in Loyalty Walkthrough 1 or Loyalty Walkthrough 2 or watch the Sandbox 101: Loyalty API video.
An accrual rule defines how buyers can earn points from the base loyalty program. The type of accrual rule used by the program determines the program type. Sellers configure their loyalty program to use one of the following ways to earn points:
Visit based - 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.
Amount spent - 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.
Item based - 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.
Category based - 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.
For more information, see Accrual rules.
Note
Sellers can also run loyalty promotions that enable buyers to earn extra points from a purchase. For more information, see Manage Loyalty Promotions.
A reward tier defines how buyers can redeem points for a discount by specifying the number of points required and the value and scope of the discount. Sellers can configure multiple reward tiers for their loyalty program that offer the following reward types:
Discount on entire sale - Offers a discount on the entire sale. The discount can be a specific amount or percentage off the entire sale:
- Amount based - A specific amount off a purchase. For example, "Redeem 10 points for a $1 discount."
- Percentage based - A percentage off a purchase, with an optional maximum discount amount. For example, "Redeem 25 points for a 20% discount, with a maximum discount of $40."
Discount on specific categories - Offers a discount on items or services that belong to specific categories in the seller's catalog. For example, suppose the seller catalog has a drink category that contains items such as tea, coffee, and hot chocolate. The discount can apply to any item in the drink category.
The discount can be an amount or percentage off one or more qualifying categories:
- Amount based - A specific amount off a purchase. For example, "Redeem 10 points for a $1 discount on a drink." If an order contains multiple drinks, the discount applies to only one item.
- Percentage based - A percentage off a purchase, with an optional maximum discount amount. For example, "Redeem 10 points for a 5% discount on a drink."
Discount on specific items - Offers a discount on specific items or services in the seller's catalog. The discount applies to only a single item in a given sale.
The discount can be a specific amount or percentage off one or more qualifying items or services:
- Amount based - A specific amount off a purchase. For example, "Redeem 10 points for a $1 discount on a coffee or cake."
- Percentage based - A percentage off a purchase, with an optional maximum discount amount. For example, "Redeem 15 points for a 10% discount on a haircut."
Free item - Offers a free item or service from the seller's catalog. For example, "Redeem 10 points to get a free coffee." The qualifying item or service is specified by the seller.
A reward that offers a free item doesn't automatically add the item to an order. However, you can create a custom UI experience to offer the free item even if it's not included in the order.
Note
Square's pricing engine applies discounts so that they maximize the reward value for the buyer. For example, consider a "Redeem 10 points for 20% off a drink" reward tier. If an order contains one coffee for $2 and one latte for $4, Square applies the discount to the higher priced latte.
Tiered rewards allow sellers to offer better discounts to buyers who spend more, as shown in the following examples:
- Reward tiers example 1:
- Tier 1 - Redeem 10 points and get a free coffee.
- Tier 2 - Redeem 15 points and get a free sandwich.
- 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 an entrée.
- Tier 2 - Redeem 20 points and get $3 off an entrée.
- Tier 3 - Redeem 30 points and get $8 off an entrée.
For some loyalty program features, the Loyalty API uses different names than the Square Dashboard or other Square products.
The earning points rule that sellers can configure in Square products is represented by an accrual rule in the Loyalty API. The type of rule used by a loyalty program determines the program type. Accrual rule settings are shown in the accrual_rules field of the LoyaltyProgram object.
A reward that sellers configure in Square products is represented by a reward tier in the Loyalty API. Reward tier settings are shown in the reward_tiers field of the LoyaltyProgram object.
A reward that you create using the Loyalty API is a contract for the buyer to redeem loyalty points for a reward tier discount. The reward can have an ISSUED, REDEEMED, or DELETED status and is associated with a loyalty account, reward tier, and (optionally) an order.