Loyalty API Overview
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. 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.
Note
For feature and pricing information, see Square Loyalty and Square Loyalty Overview. For the list of countries where Square Loyalty is available, see International availability of Square Loyalty.
After a seller sets up a loyalty program and subscribes to Square Loyalty in the Seller 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:
Obtain the buyer's phone number, which you need to provide (in E.164 format) when creating the loyalty account.
Call RetrieveLoyaltyProgram using the
main
keyword to get the ID of the seller's loyalty program.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:
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 that a buyer earned from a purchase to a 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 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 the order is paid.
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:
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.
Note
When Square creates a customer profile for a CreateLoyaltyAccount
request, the creation_source
field of the customer profile is set to LOYALTY
.
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 created using 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 add 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. The Loyalty API provides the CreateLoyaltyReward endpoint to create a reward and turn the reward into appropriate discounts by automatically updating the order. The Loyalty Walkthrough 1 and Loyalty Walkthrough 2 examples show how the 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 Seller Dashboard. The loyalty reports in the Seller 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 Seller 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 theCalculateLoyaltyPoints
endpoint to compute loyalty points and then callAccumulateLoyaltyPoints
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 theCalculateLoyaltyPoints
endpoint to compute loyalty points and then callAccumulateLoyaltyPoints
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 acategory_id
, which references theCATEGORY
catalog object that qualifies for points accrual.ITEM_VARIATION
accrual rules specify anitem_variation_id
, which references theITEM_VARIATION
catalog object that qualifies for points accrual.SPEND
accrual rules can optionally specifyexcluded_category_ids
andexcluded_item_variation_ids
, which contain the IDs of anyCATEGORY
andITEM_VARIATION
catalog objects that don't qualify for points accrual.
For more information, see Accrual rules.
Reward tiers - A reward tier defines how buyers can redeem points for discounts. Loyalty programs can include one or more reward tiers. 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
, andPRODUCT_SET
catalog objects to define the discount details for a reward. 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
andITEM_VARIATION
catalog objects that qualify for promotion points.
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 Square Loyalty Overview and Loyalty Program Overview.
International availability of Square Loyalty - Square Loyalty is currently available in the following countries: Australia, Canada, France, Ireland, Japan, Spain, the United Kingdom, and the United States. To be eligible to subscribe to Square Loyalty, the seller's Square account must be activated in a country where Square Loyalty is available. In addition, 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 andVISIT
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 Seller Dashboard.
In a
LoyaltyProgram
object, this setting corresponds to thetax_mode
field ofSPEND
orVISIT
accrual rules.Before-tip purchase amounts - For all countries, points are accrued based on purchase amounts before any added tip.
Square Loyalty subscription - The seller must have an active Square Loyalty subscription to use loyalty features. If the seller isn't an active subscriber, calls to
CreateLoyaltyAccount
,AdjustLoyaltyPoints
, andAccumulateLoyaltyPoints
return a404 NOT_FOUND
error similar to the following example. Calls to other Loyalty API endpoints might also fail.To get the subscription status, call
RetrieveLoyaltyProgram
and check thestatus
field of the returned loyalty program. Sellers can also check their subscription status in the Seller Dashboard by choosing Accounts & Settings, Business information, and then Pricing & Subscriptions. If the subscription expires, the Loyalty page displays a banner with the message "You aren't currently subscribed to Square Loyalty."One loyalty program per seller account - A Square seller account can have only one loyalty program. However, the program can be active at multiple participating locations. Sellers can have up to 10
ACTIVE
andSCHEDULED
loyalty promotions which are available in all active locations. Application must use Square version 2022-08-17 or later to work with loyalty promotions.Note that sellers can enable or disable whether buyers can accrue loyalty points for in-person purchases on a given device.
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 Seller Dashboard. Creating a program invokes the
loyalty.program.created
webhook event and updating the program invokes aloyalty.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 Seller Dashboard. Note the following:
Changing the phone number replaces the existing
LoyaltyAccount.mapping
object with a newmapping
that contains the updated phone number. This action invokes theloyalty.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 theloyalty.account.deleted
webhook event.
OAuth permissions - Applications that use OAuth require the
LOYALTY_READ
orLOYALTY_WRITE
permission to perform any Loyalty API actions. For more information, see OAuth Overview and Permissions Reference for Loyalty.Reward redemption - The following considerations apply when redeeming rewards:
While redeeming multiple rewards of different tiers on the same order is supported, redeeming multiple rewards of the same 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
andListLoyaltyPrograms
(deprecated) return anUNSUPPORTED_LOYALTY_REWARD_TIER
error. If this occurs, contact Developer Support, join our Discord community, or reach out to your Square account manager.
You can subscribe to webhook notifications for the following loyalty events.
Event | Permission | Description |
---|---|---|
loyalty.account.created | LOYALTY_READ | A loyalty account was created for a buyer. A loyalty account can be created using any of the following methods, which all publish this event: • An application calls the CreateLoyaltyAccount endpoint.• A buyer enrolls in the program from a Square Point of Sale application. • The seller enrolls a buyer using the Customer Directory. • The seller merges two customer accounts into one account using the Customer Directory. In this process, sellers might merge the two corresponding loyalty accounts by creating a new account and deleting the existing accounts. |
loyalty.account.updated | LOYALTY_READ | A loyalty account was updated. For example: • The seller updates the phone number registered for the loyalty account using the Seller Dashboard. For more information, see Square Loyalty FAQ. • Any change in the loyalty point balance, such as points added for visits, points expiration, or a manual adjustment to the point balance that a seller might perform. • The customer ID of the loyalty account was changed. For example, the loyalty account moved to another customer. |
loyalty.account.deleted | LOYALTY_READ | Published when a loyalty account is deleted. The published event does not contain the customer_id that was associated with the deleted account. The following actions to delete the account can publish this event:• The seller deletes an account using the Seller Dashboard. • The seller merges two customer profiles using the Customer Directory. In this process, sellers might merge the two corresponding loyalty accounts by creating a new account and deleting the existing accounts. |
loyalty.program.created | LOYALTY_READ | A loyalty program was created. Loyalty programs can only be created from the Seller Dashboard. |
loyalty.program.updated | LOYALTY_READ | A loyalty program was updated. Loyalty programs can only be updated from the Seller Dashboard. |
loyalty.promotion.created | LOYALTY_READ | A loyalty promotion was created. |
loyalty.promotion.updated | LOYALTY_READ | A loyalty promotion was canceled. |
loyalty.event.created | LOYALTY_READ | A balance-changing event occurred. Square Loyalty maintains a ledger of events that occur over the lifetime of a loyalty account. Square publishes notifications for each loyalty event logged to the ledger. These loyalty events are immutable, which means they are never updated or deleted. For example, when a buyer redeems a reward and then returns the order, Square publishes separate notifications for the corresponding CREATE_REWARD and DELETE_REWARD events. Similarly, Square publishes a notification for the OTHER event when points are deducted after a purchase that accrued points is refunded. |
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:
For more information about subscribing to events and validating notifications, see Square Webhooks Overview.
The following migration notes apply to the Loyalty API.
The points_multiplier
field in the LoyaltyPromotionIncentivePointsMultiplierData
object is deprecated and replaced by the new multiplier
field. This change adds support for decimal multipliers of up to three precision points. Multipliers are used in loyalty promotions that define a POINTS_MULTIPLIER
incentive type.
Deprecated in version: 2023-08-16
Retired in version: TBD
To update your CreateLoyaltyPromotion
requests when defining a POINTS_MULTIPLIER
incentive, replace points_multiplier
with multiplier
and provide a string representation of a decimal. Decimal notation is optional for multipliers that represent integer values.
The following examples represent a POINTS_MULTIPLIER
incentive that earns double points, based on the Square version:
Square version 2023-08-16 and later:
If the deprecated
points_multiplier
is provided in aCreateLoyaltyPromotion
request, Square returns both thepoints_multiplier
andmultiplier
fields in the response. Themultiplier
value is returned in three point precision (except "10.00").In addition, applications that don't integrate with the Orders API (and therefore use client-side logic to calculate promotion points) must change their logic before the
points_multiplier
field is retired. Specifically, you need to support decimal multipliers and convert themultiplier
string value to a decimal. For more information, see Calculating promotion points.Square version 2023-07-20 and earlier:
The event
field in an AccumulateLoyaltyPoints response is deprecated and replaced by the new events
field. This change allows the endpoint to return the ACCUMULATE_POINTS
and ACCUMULATE_PROMOTION_POINTS
events when a Square order specified in the request qualifies for points from the base loyalty program and an associated loyalty promotion.
Deprecated in version: 2022-08-17
Retired in version: TBD
To migrate to version 2022-08-17, update your code to handle an events
field in the AccumulateLoyaltyPoints
response:
If your application uses Orders API integration, the new
events
field can contain a singleACCUMULATE_POINTS
event or anACCUMULATE_POINTS
event and anACCUMULATE_PROMOTION_POINTS
event. Applications that integrate with the Orders API specify the ID of a Square order in theorder_id
of theAccumulateLoyaltyPoints
request.If your application uses a custom ordering system, the new
events
field always contains a singleACCUMULATE_POINTS
event. TheACCUMULATE_PROMOTION_POINTS
event is only supported for applications that use Orders API integration.
Square continues to return an empty object when a purchase doesn't qualify for loyalty points.
The following are example responses based on the Square version:
Square version 2022-08-17 and later:
Square version 2022-07-20 and earlier:
The following LoyaltyProgramAccrualRule
fields are retired and replaced by fields in new type-specific objects, as shown in the following table:
Retired field | Rule type | Replacement field |
---|---|---|
catalog_object_id | CATEGORY | category_data.category_id |
catalog_object_id | ITEM_VARIATION | item_variation_data.item_variation_id |
spend_amount_money | SPEND | spend_data.amount_money |
excluded_category_ids | SPEND | spend_data.excluded_category_ids |
excluded_item_variation_ids | SPEND | spend_data.excluded_item_variation_ids |
visit_minimum_amount_money | VISIT | visit_data.minimum_amount_money |
Retired in version: 2022-01-20
These new and retired fields are read-only from the Loyalty API, which cannot be used to create or update loyalty programs. Loyalty programs can be configured and managed only in the Seller Dashboard.
To migrate from the retired fields, you must update code that parses the accrual rules
in a RetrieveLoyaltyProgram
and ListLoyaltyPrograms
(deprecated) response. Specifically, for the accrual_rules
field of the loyalty program, your code must handle the new category_data
, item_variation_data
, spend_data
, or visit_data
fields and related data. These fields are shown in the following examples.
Example
CATEGORY
accrual rules. The newcategory_data.category_id
field replaces the retiredcatalog_object_id
field.Example
ITEM_VARIATION
accrual rules. The newitem_variation_data.item_variation_id
field replaces the retiredcatalog_object_id
field.Example
SPEND
accrual rule with the following new fields:spend_data.amount_money
replaces the retiredspend_amount_money
field.spend_data.excluded_category_ids
(optional) replaces the retiredexcluded_category_ids
field.spend_data.excluded_item_variation_ids
(optional) replaces the retiredexcluded_item_variation_ids
field.
Example
VISIT
accrual rule. The newvisit_data.minimum_amount_money
field (optional) replaces the retiredvisit_minimum_amount_money
field.Note
The
SPEND
andVISIT
accrual rule examples include thetax_mode
field that was added in Square version 2022-01-20.
The ListLoyaltyPrograms endpoint is deprecated. It's replaced by calling the RetrieveLoyaltyProgram endpoint with the main
keyword. Both endpoints are used to return the single loyalty program for a seller account.
Deprecated in version: 2021-05-13
Retired in version: TBD
To migrate to the RetrieveLoyaltyProgram
endpoint, do the following:
Update your requests. Make sure to include the
main
keyword in yourRetrieveLoyaltyProgram
request:Update code that handles responses. You must also update your code to handle the
RetrieveLoyaltyProgram
response, which returns a top-levelprogram
object instead of aprograms
array. The following excerpts show the difference between the responses from the two endpoints.Excerpt from a
RetrieveLoyaltyProgram
response that returns aprogram
object:Excerpt from a
ListLoyaltyPrograms
(deprecated) response that returns aprograms
array:
A loyalty account mapping is used to associate the loyalty account with a buyer by phone number. The following mapping-related fields are retired:
In the LoyaltyAccount object, the
mappings
field is retired and replaced bymapping
.In the LoyaltyAccountMapping object, the
type
andvalue
fields are retired and replaced byphone_number
.
Retired in version: 2021-05-13
In Square version 2021-05-13 and later:
The
mappings
field isn't accepted inCreateLoyaltyAccount
requests.The
type
andvalue
fields aren't accepted inCreateLoyaltyAccount
orSearchLoyaltyAccounts
requests.The
mappings
,type
, andvalue
fields aren't returned in responses.
To migrate to the required mapping implementation, do the following:
Update your requests.
In your
CreateLoyaltyAccount
requests, you must usemapping
andphone_number
instead ofmappings
,type
, andvalue
, as shown in the following example:In your
SearchLoyaltyAccounts
requests that query by phone number, you must usephone_number
instead oftype
andvalue
, as shown in the following example. Note thatmappings
is still a valid search query filter.
Update code that handles responses. You must update your code to handle returned loyalty accounts that include only the
mapping
andphone_number
fields. The following example responses show the changes in a returnedloyalty_account
object.Example
CreateLoyaltyAccount
response in Square version 2021-05-13 and later:Example
CreateLoyaltyAccount
response in Square version 2021-04-21:Note
The
mapping
field was added in Square version 2021-04-21, so earlier versions only returnmappings
.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.