Applies to: Loyalty API | Orders API
Learn how to use the Loyalty API to accumulate or adjust points for a loyalty account.
Buyers can earn loyalty points from qualified purchases and redeem points for reward discounts. The balance
field of a loyalty account represents the number of points that can be used to create and redeem a reward.
The Loyalty API supports the following operations for working with loyalty points:
- Accumulate loyalty points from a purchase
- Adjust loyalty points manually
- Calculate loyalty points for a purchase
Note
To get the available point balance for a loyalty account, call RetrieveLoyaltyAccount or SearchLoyaltyAccounts and check the balance
field.
Call AccumulateLoyaltyPoints to add points earned from a purchase to a loyalty account. The information you provide in the request depends on whether your application uses the Orders API to process orders.
The accrual rules of a loyalty program determine whether a purchase qualifies for program points. Purchases that qualify for points from the base loyalty program might also qualify for points from a loyalty promotion.
If your application uses the Orders API to process orders, provide the following information in the AccumulateLoyaltyPoints
request:
account_id
with the ID of the target loyalty account. To get the account ID, call SearchLoyaltyAccounts and search using a phone number or customer ID.accumulate_points
with anorder_id
field that specifies the ID of the associated order. The order must be in theCOMPLETED
state. Square reads the order and computes the number of program points and promotion points earned from the purchase.location_id
with the ID of the location where the purchase was made. You can get this ID from the order.idempotency_key
with a unique identifier for this request, which is used to ensure idempotency.
Accumulate loyalty points
For purchases that qualify for multiple accrual rules, Square computes points based on the accrual rule that grants the most points. For purchases that qualify for multiple promotions, Square computes points based on the most recently created promotion. A purchase must first qualify for program points to be eligible for promotion points.
Note
To see a typical application flow for adding earned points to a loyalty account, see Accumulate Loyalty Points for a Buyer.
When the purchase qualifies for points, Square returns loyalty events that represent the changes to the point balance. Square generates a searchable event each time the balance changes.
- If program points are added, the response contains an
ACCUMULATE_POINTS
event. - If promotion points are added, the response also contains an
ACCUMULATE_PROMOTION_POINTS
event.
The following example response contains an ACCUMULATE_POINTS
event. This single event indicates that the purchase only qualifies for program points.
{
"events": [
{
"id": "bbd1ef00-92ac-3e5f-8887-cd3c6ba29313",
"type": "ACCUMULATE_POINTS",
"created_at": "2022-09-07T22:31:48Z",
"accumulate_points": {
"loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
"points": 12,
"order_id": "cb9LSpDgOH3rITBaZ6eIBb9ee4F"
},
"loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
"location_id": "S8GWD509MEHCA",
"source": "LOYALTY_API"
}
]
}
The following example response contains an ACCUMULATE_POINTS
event and ACCUMULATE_PROMOTION_POINTS
event:
{
"events": [
{
"id": "bbd1ef00-92ac-3e5f-8887-cd3c6ba29313",
"type": "ACCUMULATE_POINTS",
"created_at": "2022-09-07T22:31:48Z",
"accumulate_points": {
"loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
"points": 12,
"order_id": "cb9LSpDgOH3rITBaZ6eIBb9ee4F"
},
"loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
"location_id": "S8GWD509MEHCA",
"source": "LOYALTY_API"
},
{
"id": "b525f003-47ea-43aa-bb18-6d12cde50637",
"type": "ACCUMULATE_PROMOTION_POINTS",
"created_at": "2022-09-07T22:31:51Z",
"accumulate_points": {
"loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
"points": 5,
"order_id": "cb9LSpDgOH3rITBaZ6eIBb9ee4F"
},
"loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
"location_id": "S8GWD509MEHCA",
"source": "LOYALTY_API"
}
]
}
If the purchase doesn't qualify for points, Square returns an empty object.
{}
If your application uses a custom ordering system to process orders (instead of the Orders API), provide the following information in the AccumulateLoyaltyPoints
request:
account_id
with the ID of the target loyalty account. To get the account ID, call SearchLoyaltyAccounts and search using a phone number or customer ID.accumulate_points
with apoints
field that specifies the number of program points and promotion points to add to the account. You must first use client-side logic to compute the number of points earned from the purchase. For more information, see Computing points earned from a purchase.location_id
with the ID of the location where the purchase was made.idempotency_key
with a unique identifier for this request, which is used to ensure idempotency.
Accumulate loyalty points
Square returns an ACCUMULATE_POINTS
loyalty event that represents the change to the point balance. Square generates a searchable event each time the balance changes.
The following is an example response:
{
"events": [
{
"id": "bbd1ef00-92ac-3e5f-8887-cd3c6ba29313",
"type": "ACCUMULATE_POINTS",
"created_at": "2020-05-07T22:31:48Z",
"accumulate_points": {
"loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
"points": 7
},
"loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
"location_id": "S8GWD509MEHCA",
"source": "LOYALTY_API"
}
]
}
For applications that don't use the Orders API to process orders, the events
field contains a single ACCUMULATE_POINTS
event. The ACCUMULATE_PROMOTION_POINTS
event type is returned only when using Orders API integration.
Applications that use a custom ordering system can use the following process to compute the points earned from a purchase:
Call RetrieveLoyaltyProgram using the
main
keyword (or the loyalty program ID, which is specified in the loyalty account).Check the
accrual_rules
field in the response. Each accrual rule defines the program type (SPEND
,VISIT
,CATALOG
, orITEM_VARIATION
) in theaccrual_type
field, along with additional data that specifies the conditions for earning points from the base loyalty program. For purchases that qualify for multiple accrual rules, use the accrual rule that grants the most points.Note
For
SPEND
program types andVISIT
program types with a minimum spend requirement, you can call CalculateLoyaltyPoints and provide the purchase amount to get the number of program points the purchase qualifies for. Make sure to check thevisit_data.tax_mode
orspend_data.tax_mode
field in the accrual rule to determine whether tax should be included in the purchase amount.If the purchase qualifies for program points, check whether it also qualifies for points from an associated loyalty promotion. For purchases that qualify for multiple promotions, use the most recently created promotion. For more information, see Calculating promotion points.
Provide the combined program points and promotion points earned from the purchase in the
points
field of theAccumulateLoyaltyPoints
request.