Retrieve a Loyalty Program
After Square sellers subscribe to Square Loyalty and set up their loyalty program, you can use the Loyalty API to get information about the program, such as the accrual rules and reward tiers.
The Loyalty API supports the following operations for working with loyalty programs:
List loyalty programs (deprecated)
Note
The Loyalty API cannot be used to create or update loyalty programs. For information about how sellers set up accrual rules and reward tiers for their loyalty program, see Loyalty Program Overview.
LoyaltyProgram object
The following is an example LoyaltyProgram
object:
This example loyalty program allows buyers to accrue one point for every $2 spent on qualifying items and offers two percentage-based reward tiers.
The following fields represent key attributes of a loyalty program:
Field | Description |
---|---|
status | The status of the loyalty program, which is determined by the status of the seller's Square Loyalty subscription. All write operations in the Loyalty API require that the loyalty program is ACTIVE . |
location_ids | The IDs of the participating locations in the loyalty program. |
accrual_rules | Contains one or more accrual rules that define how buyers can earn points from purchases. Loyalty programs can contain a single type of accrual rule: • CATEGORY . Can include one or more accrual rules.• ITEM_VARIATION . Can include one or more accrual rules.• SPEND . Can include one accrual rule.• VISIT . Can include one accrual rule.Accrual rules use the category_data , item_variation_data , spend_data , or visit_data field to define additional data for the rule type.CATEGORY , ITEM_VARIATION , and SPEND accrual rules integrate with the Catalog API. For more information, see Integration with the Catalog API.
|
expiration_policy | The number of months before points expire, in P[n]M RFC 3339 duration format. For example, a value of P12M represents a duration of 12 months. This field is present only if the loyalty program has an expiration policy. For information about how sellers configure an expiration policy, see Add Points Expiration Date in Create a Loyalty Program with Square.Loyalty accounts that have expiring points include an expiring_point_deadlines field. |
terminology | The terminology used to represent points. For example, Point or Points and Star or Stars. |
reward_tiers | Contains one or more reward tiers that define how buyers can redeem points for rewards. To get information about the reward tier discount, call the RetrieveCatalogObject endpoint using the object_id and catalog_version from the pricing_rule_reference field. Make sure to set include_related_objects to true . For more information, see Integration with the Catalog API
and Getting discount details for a reward tier.
Note Loyalty reward tiers currently include the deprecated definition field, which is replaced by the pricing_rule_reference field. When possible, you should use pricing_rule_reference . |
Retrieve a loyalty program
Call RetrieveLoyaltyProgram to get a loyalty program by the program ID or using the main
keyword. A seller account can contain only one loyalty program, so either value can be used to retrieve the loyalty program that belongs to the seller.
Retrieve a loyalty program by the program ID.
Retrieve a loyalty program using the
main
keyword.Note
Only the
RetrieveLoyaltyProgram
endpoint supports using themain
keyword in place of the program ID. For example, you cannot usemain
to callCalculateLoyaltyPoints
.
The following is an example RetrieveLoyaltyProgram
response:
Square returns a 404 NOT_FOUND
error if the seller has never subscribed to Square Loyalty.
List loyalty programs (deprecated)
Call ListLoyaltyPrograms to list the loyalty programs in a seller's account. A seller account can contain one loyalty program, so only one loyalty program is returned in the list.
Note
The ListLoyaltyPrograms
endpoint is deprecated. When possible, you should use the RetrieveLoyaltyProgram endpoint with the main
keyword instead. RetrieveLoyaltyProgram
and ListLoyaltyPrograms
provide the same functionality because a seller account can contain only one loyalty program. For more information, see Migration notes.
The following is an example ListLoyaltyPrograms
response:
Square returns an empty object if the seller has never subscribed to Square Loyalty.
Related topics
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.