Loyalty API

Applies to: Loyalty API | Customers API | Orders API | Catalog API | GraphQL

Learn about the Loyalty API and how to set up a loyalty program, enroll buyers in the program, accrue points, and redeem points.

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. Loyalty programs help drive repeat visits to businesses by allowing customers to earn points that can be redeemed for future discounts. Developers can use the Loyalty API to integrate Square Loyalty into third-party applications, such as eCommerce websites, mobile applications, and POS solutions.

Watch the following video to see how the API works:

The following requirements and limitations apply when integrating the Square loyalty program in applications using the Loyalty API. For more information about loyalty programs, including pricing information, see Overview of Square Loyalty and Loyalty Program.

• International availability of Square Loyalty - Square Loyalty is available in Australia, Canada, France, Ireland, Japan, Spain, the United Kingdom, and the United States. The country code of the phone number used to create a loyalty account must correspond to a country where Square Loyalty is available.

  Square applies the following accrual logic for SPEND program types and VISIT program types that have a minimum spend requirement:

  • Before-tax versus after-tax purchase amounts - By default, the country of the seller account determines whether points accrual is based on the before-tax or after-tax purchase amount:

    • Seller accounts activated in Canada and the United States use the before-tax purchase amount.
    • Seller accounts activated in Australia, France, Ireland, Japan, Spain, and the United Kingdom use the after-tax purchase amount.

    Sellers can also configure the before-tax or after-tax points accrual setting on the Settings page in the Loyalty section of the Square Dashboard.

    In a LoyaltyProgram object, this setting corresponds to the tax_mode field of SPEND or VISIT accrual rules.

  • Before-tip purchase amounts - For all countries, points are accrued based on purchase amounts before any added tip.

• Loyalty programs are read-only with the Loyalty API - The Loyalty API cannot be used to create or modify loyalty program settings. Sellers can configure their loyalty program only on the Loyalty page of the Square Dashboard. Creating a program invokes the loyalty.program.created webhook event and updating the program invokes a loyalty.program.updated event. Note that the Loyalty API can be used to create and manage loyalty promotions for a loyalty program.

• Limited support for loyalty promotions for custom ordering applications - For applications that use a custom ordering system to process orders (instead of the Orders API), Square provides limited support for managing promotion points for buyers. For more information, see Considerations.

• Limited support for managing loyalty accounts with the Loyalty API - The Loyalty API lets you create loyalty accounts and manage points and rewards for loyalty accounts, but it cannot be used to update account settings or delete accounts. However, sellers can change the phone number for an account or delete an account from the customer's Loyalty Summary tile in the Square Dashboard. Note the following:

  • Changing the phone number replaces the existing LoyaltyAccount.mapping object with a new mapping that contains the updated phone number. This action invokes the loyalty.account.updated webhook event. The phone number assigned to the associated customer profile isn't affected.

  • Deleted loyalty accounts are permanently removed from the seller account and don't appear in SearchLoyaltyAccounts results. This action invokes the loyalty.account.deleted webhook event.

• OAuth permissions - Applications that use OAuth require the LOYALTY_READ or LOYALTY_WRITE permission to perform any Loyalty API actions. For more information, see OAuth API and Permissions Reference for Loyalty.

• Reward redemption - The following considerations apply when redeeming rewards:

  • Redeeming multiple rewards from different reward tiers on the same order is supported, but redeeming multiple rewards from the same reward tier on the same order isn't supported.
  • When redeeming multiple rewards on the same order, only one reward can apply to each line item. Consequently, redeeming multiple whole purchase rewards leads to the highest discount being used and others being ignored.
  • If a reward tier references an invalid catalog item, or another condition prevents the Loyalty API from converting a reward tier, calls to RetrieveLoyaltyProgram and ListLoyaltyPrograms (deprecated) return an UNSUPPORTED_LOYALTY_REWARD_TIER error. If this occurs, contact Developer Support, join our Discord community, or reach out to your Square account manager.

After a seller sets up a loyalty program and subscribes to Square Loyalty in the Square Dashboard, you can create loyalty accounts to enroll buyers in the loyalty program. Then, buyers can start earning points from purchases and redeeming points for reward discounts.

To enroll a buyer in a loyalty program, you create a loyalty account for the buyer:

1. Obtain the buyer's phone number, which you need to provide (in E.164 format) when creating the loyalty account.

2. Call RetrieveLoyaltyProgram using the main keyword to get the ID of the seller's loyalty program.

3. Call CreateLoyaltyAccount to create a loyalty account in the loyalty program. The loyalty account is associated with a customer profile in the seller's Customer Directory. If a matching customer profile cannot be found, a new customer profile is created. For more information, see Create a loyalty account.

   After you create the loyalty account, you can enable the buyer to earn (accumulate) points from purchases and redeem points for reward discounts:

   • Accumulate points from a purchase
   • Redeem points for a reward discount

   Note

   If your application uses the Orders API, Square provides a simplified process for accumulating and redeeming loyalty points.

When you're ready to try calling the Loyalty API, you can watch the Sandbox 101: Loyalty API video or follow step 1 in walkthrough 1 or walkthrough 2 to set up a loyalty program in the Square Sandbox and subscribe to Square Loyalty for free. You can then continue with the walkthrough steps or build and send test API requests using API Explorer.

You can use Loyalty API endpoints to perform the following operations:

• RetrieveLoyaltyProgram - Get information about a loyalty program, such as the program ID used to create a loyalty account and the program's accrual rules and reward tiers.

  For more information, see Retrieve a Loyalty Program.

• CreateLoyaltyPromotion - Create a loyalty promotion that enables buyers to earn extra points.

• RetrieveLoyaltyPromotion - Get information about a loyalty promotion, such as the promotion status, incentive, and available time.

• ListLoyaltyPromotions - List the loyalty promotions associated with a loyalty program.

• CancelLoyaltyPromotion - Cancel a loyalty promotion.

  For more information, see Manage Loyalty Promotions.

• CreateLoyaltyAccount - Create a loyalty account that enrolls a buyer in a loyalty program.

• RetrieveLoyaltyAccount - Get information about a loyalty account, such as the available point balance and associated customer ID.

• SearchLoyaltyAccounts - List all loyalty accounts, or search accounts by one or more phone number mappings or customer IDs.

  For more information, see Create and Retrieve Loyalty Accounts.

• AccumulateLoyaltyPoints - Add points earned from a purchase to a buyer's loyalty account.

• AdjustLoyaltyPoints - Add or remove points from a loyalty account outside of the normal order-purchase flow. For example, you might call this endpoint to give extra points for a special offer or remove points after an item is returned.

• CalculateLoyaltyPoints - Get the number of points a buyer would earn from a purchase, which you can display while building the order. If your application doesn't integrate with the Orders API, you can also call this endpoint to help compute the points to provide to the AccumulateLoyaltyPoints endpoint.

  For more information, see Manage Loyalty Points.

• CreateLoyaltyReward - Issue a loyalty reward, which removes the required points from the loyalty account balance and holds them in reserve until the reward is redeemed or deleted.

• RedeemLoyaltyReward - Redeem a loyalty reward, which permanently removes the points from the loyalty account balance. If your application integrates with the Orders API, Square automatically calls this endpoint after an order is paid to redeem any eligible rewards that you created for the order.

• RetrieveLoyaltyReward - Get information about a loyalty reward.

• SearchLoyaltyRewards - List all loyalty rewards, or search rewards by a loyalty account ID and then optionally by a reward status.

• DeleteLoyaltyReward - Delete a reward that was issued but not redeemed.

  For more information, see Manage Loyalty Rewards.

• SearchLoyaltyEvents - List all events that resulted in a change to the loyalty point balance, or search events by a loyalty account ID, date range, and other supported attributes.

  For more information, see Search for Balance-Changing Loyalty Events.

  Note

  You can also subscribe for webhook notifications about all loyalty events.

Loyalty programs have built-in integration with the following Square APIs:

• Customers API
• Orders API
• Catalog API

All loyalty accounts have a customer_id field that associates the account with a customer profile in the seller's Customer Directory. This association enables integration features such as searching loyalty accounts by customer ID and accessing loyalty activity from the customer's Loyalty Summary card in the directory.

When possible, you should provide a customer_id in the CreateLoyaltyAccount request when you enroll buyers in a loyalty program. If customer_id isn't provided, Square uses the phone number provided in the request to search the directory for a matching customer profile. If a match isn't found, Square creates a new customer profile and associates it with the loyalty account. However, this process can result in duplicate profiles if the buyer's customer profile doesn't have a matching phone number. To avoid creating duplicate customer profiles, call SearchCustomers to search customer profiles by another identifying attribute, such as email address or reference ID before creating the account.

The Loyalty API is integrated with the Orders API and you should leverage this in your applications. Some of the benefits are:

• A simplified point accrual flow. The following Loyalty API endpoints let you easily compute the points earned on orders you create with the Orders API:

  • The CalculateLoyaltyPoints endpoint computes program points and promotion points for the specified order.
  • The AccumulateLoyaltyPoints endpoint computes program points and promotion points for the specified order and adds the points to the loyalty account of the buyer.

  Square also automatically adjusts loyalty points when an order is refunded, depending on the program type and refund type. For more information, see Customer and Refunds in Square Loyalty FAQ.

• A simplified reward redemption flow. If you provide an order ID when you call the CreateLoyaltyReward endpoint to create a reward, Square automatically updates the order with appropriate discounts and redeems the reward after the order is paid. The Loyalty Walkthrough 1 and Loyalty Walkthrough 2 examples show how this integration works.

  The Orders API provides an added benefit when working with multiple discounts on an order. The pricing engine that Square provides can aggregate multiple discounts from various sources. Without the Orders API, you need to write code to accomplish this task.

• Useful reporting in the Square Dashboard. The loyalty reports in the Square Dashboard provide useful metrics about how the loyalty program is working:

  • The Visits report uses order data to show the number of visits by first-time and repeat loyalty buyers and the average visits by loyalty and non-loyalty buyers.

  • The Sales report shows the sales amount and average amount spent by loyalty and non-loyalty buyers.

    The Square Dashboard also shows the Top Customers report.

Depending on the program type, your development costs might be higher if you don't use the Orders API for order processing. However, the following loyalty programs are easy to implement without using the Orders API:

• A loyalty program that offers visit-based accrual - Consider this VISIT accrual rule: "Earn one point for every visit, with a minimum purchase of $10." In this case, you can add points to the buyer's account with minimal code. You don't need itemized orders. For example, suppose a buyer pays $15 for an order. You can use the CalculateLoyaltyPoints endpoint to compute loyalty points and then call AccumulateLoyaltyPoints to add the points to the buyer's account.

• A loyalty program that offers amount-spent accrual - Consider this SPEND accrual rule: "Earn one point for each dollar spent." You can use the CalculateLoyaltyPoints endpoint to compute loyalty points and then call AccumulateLoyaltyPoints to add the points to the loyalty account of the buyer. This doesn't require matching any order line items to compute the loyalty points.

Note that the accrual logic used to calculate the number of points earned depends on the tax-mode setting of the VISIT or SPEND accrual rule. If you use the Orders API, these amounts are known and the points are computed appropriately without the need of additional code.

A loyalty program contains accrual rules and reward tiers, both of which are integrated with the Catalog API.

• Accrual rules - 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. For example, a Category-based program type is configured using one or more CATEGORY accrual rules.

  The following rule types integrate with the Catalog API:

  • CATEGORY accrual rules specify a category_id, which references the CATEGORY catalog object that qualifies for points accrual.

  • ITEM_VARIATION accrual rules specify an item_variation_id, which references the ITEM_VARIATION catalog object that qualifies for points accrual.

  • SPEND accrual rules 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.

• Reward tiers - Loyalty programs can include one or more reward tiers. A reward tier defines how buyers can redeem points for discounts. For example, a reward tier might represent a reward such as "Redeem 10 points for 10% off your entire purchase."

  A loyalty reward tier uses PRICING_RULE, DISCOUNT, and PRODUCT_SET catalog objects to define the discount details for a reward. A reward tier definition is a read-only integration with the Catalog API that's pinned to a specific catalog version. For more information, see Get discount details for a reward tier.

• Loyalty promotions - Loyalty promotions enable buyers to earn extra points in addition to points earned from the base loyalty program. Category-based and item-based promotions specify the IDs of CATEGORY and ITEM_VARIATION catalog objects that qualify for promotion points.

A Square seller must have an active Square Loyalty subscription to use loyalty features. To find a seller's subscription status, call RetrieveLoyaltyProgram and check the status field (either ACTIVE or INACTIVE) of the returned loyalty program.

With inactive subscriptions, write operations such as CreateLoyaltyAccount, AdjustLoyaltyPoints, and AccumulateLoyaltyPoints return the 404 NOT_FOUND error shown in the following example. Calls to other Loyalty API endpoints might also fail.

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

The Loyalty API cannot be used to create or update a loyalty program. Your application can direct sellers to the Square Dashboard where they can subscribe to Square Loyalty and set up their loyalty program. They can also check their subscription status and resubscribe in the Square Dashboard by choosing Settings, Accounts & Settings, Business information, and Pricing & subscriptions. If the subscription has expired, the Loyalty page displays a banner with the message "You aren't currently subscribed to Square Loyalty" along with a Subscribe link.

A Square seller can have only one loyalty program. However, the program can be active at multiple participating locations. Sellers can also have up to 10 ACTIVE and SCHEDULED loyalty promotions, which are available in all active locations.

Note that sellers can enable or disable whether buyers can accrue loyalty points for in-person purchases on a given device.

You can subscribe to webhook notifications for the following loyalty events.

All notifications include the corresponding loyalty_account, loyalty_event, loyalty_program, or loyalty_promotion object, as shown in the following excerpt of an example loyalty.account.created notification:

{
  "merchant_id": "6QJXJGB6AZFN7",
  "type": "loyalty.account.created",
  "event_id": "45957f82-1e7e-42a3-9532-a4e787c3344c",
  "created_at": "2021-07-13T17:37:11Z",
  "data": {
    "type": "loyalty_account",
    "id": "dd17bfc8-178a-456c-ba4e-dae5813d429f",
    "object": {
      "loyalty_account": {
        // loyalty account fields
      }
    }
  }
}

For more information about subscribing to events and validating notifications, see Square Webhooks.

• Loyalty Program
• Loyalty API Example Walkthrough 1
• Loyalty API Example Walkthrough 2
• Square Loyalty Pricing
• Video: Sandbox 101: Loyalty API
• API Reference: Loyalty