Loyalty API

Loyalty Program Overview

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 Seller Dashboard. For feature and pricing information, see Square Loyalty and Square Loyalty Overview. For the list of countries where Square Loyalty is available, see Availability of Square Loyalty.

Square provides a Loyalty API that developers can use to integrate Square Loyalty into their applications, such as eCommerce websites, mobile applications, or POS solutions. For more information, see Manage Loyalty Accounts Using the Loyalty API.

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

After a seller subscribes to Square Loyalty and sets up their loyalty program, applications can use the Loyalty API to create and manage loyalty accounts. When setting up a Square loyalty program in the Seller Dashboard, sellers configure accrual rules and reward tiers.

Note

To test your calls to the Loyalty API, you can set up a loyalty program for your own Square account. The Loyalty Walkthrough 1 and Loyalty Walkthrough 2 topics include steps for setting up a loyalty program in the Sandbox environment.

The Loyalty API cannot be used to create or update loyalty programs.

Accrual rules Permalink Get a link to this section

An accrual rule defines how buyers can earn points. Square loyalty programs support the following ways to accrue points:

loyalty_program_types

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

Amount spent. Buyers earn points based on the amount they spend. For example, "Earn one point for every $2 dollars spent."

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.

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.

Note

The country of the seller's Square account determines whether tax is included in the purchase amount by default when accruing points for amount-spent and visit-based programs. For more information, see Availability of Square Loyalty.

Reward tiers Permalink Get a link to this section

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. A loyalty program can offer multiple reward tiers. Square loyalty programs support the following reward types:

loyalty_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 does not automatically add the item to an order. However, you can create a custom UI experience to offer the free item even if it is 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.

Loyalty feature names in the Loyalty API Permalink Get a link to this section

For some loyalty features, the Loyalty API uses different names than the Seller Dashboard or other first-party applications.

The program type (or earning points rule) that sellers configure in first-party applications are represented by an accrual rule in the Loyalty API. Accrual rule settings are defined in the accrual_rules field of the LoyaltyProgram object.

A reward that sellers configure in first-party applications is represented by a reward tier in the Loyalty API. Reward tier settings are defined 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.

Related topics Permalink Get a link to this section