Loyalty promotions can provide incentives for customers to change their buying behavior to earn extra loyalty points. For example, customers might be willing to try new products and services or make purchases at certain times of day. Promotions offer point-based incentives (for example, earn double points or earn five additional points) and can be scheduled to run indefinitely or at certain times.
The Loyalty API supports the following operations for working with loyalty promotions:
- Create a loyalty promotion
- Retrieve a loyalty promotion
- List loyalty promotions
- Cancel a loyalty promotion
A loyalty promotion extends the base loyalty program. Buyers earn promotion points only if the purchase meets both the conditions of an accrual rule in the base loyalty program and the conditions of the loyalty promotion. A purchase can earn points for only one promotion. If a purchase qualifies for multiple promotions, Square selects the most recently created promotion.
If your application uses the Orders API to process orders, Square provides built-in integration for managing the points buyers earn from loyalty promotions. For more information, see Considerations.
The following example promotion gives buyers double points every Tuesday from 4 PM to 6 PM:
{
"loyalty_promotion": {
"id": "loypromo_f0f9b849-725e-378d-b810-511237e07b67",
"name": "Tuesday Happy Hour",
"incentive": {
"type": "POINTS_MULTIPLIER",
"points_multiplier_data": {
"multiplier": "2.000"
}
},
"available_time": {
"start_date": "2022-08-16",
"time_periods": [
"BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"
]
},
"trigger_limit": {
"times": 1,
"interval": "DAY"
},
"qualifying_category_ids": [
"XTQPYLR3IIU9C44VRCB3XD12",
"D3RYL4VRCM7CJ56IXERSTAKM"
],
"status": "ACTIVE",
"created_at": "2022-08-16T08:38:54Z",
"updated_at": "2022-08-16T08:38:54Z",
"loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
}
}
The following table describes key loyalty promotion settings. For information about all available settings, see LoyaltyPromotion.
Field | Description |
---|---|
incentive | The points incentive that determines the number of promotion points earned are specified using one of the following:
|
| The scheduling information that defines when purchases can qualify to earn promotion points. Square sets the |
trigger_limit | The number of times a buyer can trigger the promotion to earn points during a set interval (for example, three times per day). If not specified, buyers can trigger the promotion an unlimited number of times. |
minimum_spend_amount_money | The minimum purchase amount required to earn promotion points. If not specified, the promotion has no minimum purchase requirement. |
| The catalog items that qualify for the promotion, which are valid only for If If |
| The status of the promotion: Square sets the status according to the |
loyalty_program_id | The ID of the loyalty program associated with the promotion (also referred to as the base loyalty program). |
When a loyalty promotion has an ACTIVE
status, customers can earn promotion points for purchases that meet the conditions for both the base loyalty program and the loyalty promotion. Loyalty promotion conditions are determined by the following fields:
available_time
minimum_spend_amount_money
qualifying_category_ids
orqualifying_item_variation_ids
trigger_limit
For more information, see Create a loyalty promotion or Calculating promotion points.
The available_time
field of a loyalty promotion defines when purchases can qualify to earn promotion points. The scheduling details are specified in the time_periods
field using a list of iCalendar (RFC 5545) events (VEVENT
). Each event represents an available time period per day or days of the week, which can be defined explicitly or implicitly. A day can have a maximum of one available time period.
The following VEVENT
fields are supported:
DTSTART
- Required. A timestamp of when the time period starts. The time portion must be in local (unzoned) time format. For example,DTSTART:20230101T090000
.DURATION
- Required. The duration of the time period, relative to theDTSTART
timestamp. For example,DURATION:PT3H30M
represents 3 hours and 30 minutes.RRULE
- The recurrence rule for the time period. For example,RRULE:FREQ=WEEKLY;BYDAY=TH
represents a recurrence on Thursdays. OnlyFREQ=WEEKLY
is supported. To specify an end date, use theUNTIL
keyword. To schedule a promotion to run 1 day only, omit theRRULE
field.
After the promotion is created:
- Square sets the
start_date
to the earliest date specified. When thestart_date
is reached, Square sets thestatus
of the promotion toACTIVE
. - If end dates are specified, Square sets the
end_date
to the latest date specified. When theend_date
is reached, Square sets thestatus
toENDED
. Loyalty promotions that have no end date run until the promotion is canceled.
The event in the following example defines a promotion that starts August 17, 2022, and is available every Monday, Wednesday, and Friday from 5 PM to 7 PM:
[
"BEGIN:VEVENT
DTSTART:20220817T170000
DURATION:P2H
RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
END:VEVENT"
[
The two events in the following example define a promotion that starts December 1, 2022, and is available every Monday from 10 AM to 3:30 PM and Thursday from 11 AM to 3 PM:
[ “BEGIN:VEVENT DTSTART:20221205T100000 DURATION:PT5H30M RRULE:FREQ=WEEKLY;BYDAY=MO END:VEVENT”, “BEGIN:VEVENT DTSTART:20221201T110000 DURATION:PT4H0M RRULE:FREQ=WEEKLY;BYDAY=TH END:VEVENT” ]
The event in the following example defines a promotion that starts October 1, 2022, and is available every Tuesday until October 31, 2023:
[
"BEGIN:VEVENT
DTSTART:20220816T160000
DURATION:PT2H
RRULE:FREQ=WEEKLY;UNTIL=20221001T000000;BYDAY=TU
END:VEVENT"
]
The event in the following example defines a promotion that is available only on September 5, 2022, from 9 AM to 9 PM:
[
"BEGIN:VEVENT
DTSTART:20220905T090000
DURATION:PT12H
END:VEVENT"
]
Note that BEGIN:VEVENT
and END:VEVENT
are optional in a CreateLoyaltyPromotion
request but are always included in the response.
The qualifying_category_ids
and qualifying_item_variation_ids
fields of a loyalty promotion define whether a purchase must contain a qualifying item to be eligible for promotion points. A promotion can specify qualifying categories or qualifying item variations, but not both.
Category-based or item-based promotions are supported only for VISIT
and SPEND
program types. Because SPEND
program types can optionally specify excluded categories or item variations, you should be aware of the following requirements:
When creating a category-based or item-based promotion, don't specify any categories or item variations that are excluded from the base loyalty program.
When calculating whether a purchase qualifies for points from a category-based or item-based promotion, don't grant promotion points based on any excluded categories or item variations.
To calculate category-based and item-based promotion points accurately, orders must reference ITEM_VARIATION
catalog objects by ID. For example, when using the Orders API to create orders, each order line item must specify the ID of the corresponding item variation in the catalog_object_id
field.
Use the following process to verify that qualifying promotional items don't conflict with items that are excluded in the accrual rule:
Call RetrieveLoyaltyProgram to retrieve the base loyalty program.
In the returned loyalty program, if the
accrual_rules
field contains an accrual rule of theSPEND
type, check whetherexcluded_category_ids
orexcluded_item_variation_ids
is defined.The following example excerpt is a
SPEND
accrual rule that defines both fields:... "accrual_rules": [ { "accrual_type": "SPEND", "points": 1, "spend_data": { "amount_money": { "amount": 500, "currency": "USD" }, "excluded_category_ids": [ "7ZERJKO5PVYXCVUHV2JCZ2UG", "FQKAOJE5C4FIMF5A2URMLW6V" ], "excluded_item_variation_ids": [ "CBZXBUVVTYUBZGQO44RHMR6B", "EDILT24Z2NISEXDKGY6HP7XV" ], "tax_mode": "BEFORE_TAX" } } ] ...When creating a category-based or item-based promotion
- If
excluded_category_ids
is defined in the accrual rule:qualifying_category_ids
in the promotion cannot include an excluded category.qualifying_item_variation_ids
in the promotion cannot include an item variation that belongs to an excluded category.
- If
excluded_item_variation_ids
is defined in the accrual rule:qualifying_item_variation_ids
in the promotion cannot include an excluded item variation.
When calculating points for category-based or item-based promotions
If
excluded_category_ids
is defined in the accrual rule, don't grant promotion points based on item variations in the purchase that belong to an excluded category.If
excluded_item_variation_ids
is defined in the accrual rule, don't grant promotion points based on item variations in the purchase that are excluded.Note
This check applies only to custom ordering applications because Square automatically calculates promotion points for orders that are processed with the Orders API. For more information, see Calculating promotion points.
To determine which category one or more item variations belong to:
- Call BatchRetrieveCatalogObjects and set
include_related_objects
totrue
. Forobject_ids
, specify the ID of each item variation. - In the
related_objects
field of the response, check thecategory_id
of theITEM
catalog object that corresponds to the item variation. Note that the corresponding item is referenced in the item variation'sitem_id
field.
- If
To create a loyalty promotion, call CreateLoyaltyPromotion and provide the following information:
- The
program_id
path parameter with the ID of the associated loyalty program. You can get the program ID from the loyalty promotion or by calling RetrieveLoyaltyProgram using themain
keyword. - The
loyalty_promotion
field with the following fields:incentive
with the points incentive for the promotion:To multiply the points earned from the base loyalty program, specify
POINTS_MULTIPLIER
fortype
and providepoints_multiplier_data
with themultiplier
value specified as a string representation of a decimal. For example, to allow buyers to earn promotion points equal to 1.5x the program points, set the value to"1.5"
. Fractional points earned for a promotion are dropped.Square supports multipliers up to 10x, with optional three point precision for decimal multipliers. In the request, you can specify a maximum of five characters ranging from
"1.001"
-"10.00"
. Square returns the multiplier in three point precision (except"10.00"
).To define a static number of promotion points, specify
POINTS_ADDITION
fortype
and providepoints_addition_data
with thepoints_addition
value. For example, to allow buyers to earn 3 extra points, set the value to 3.
available_time
with scheduling information specified as iCalendar events in thetime_periods
field. Square uses this event data to populate thestart_date
and (optional)end_at
fields and to set the loyalty promotion to theACTIVE
orSCHEDULED
status. For more information, see Available time.trigger_limit
with thetimes
andinterval
fields that specify the number of times a buyer can trigger the promotion to earn points. If not specified, buyers can trigger the promotion an unlimited number of times.minimum_spend_amount_money
with the minimum purchase amount required to earn promotion points. If specified, this amount is positive. If not specified, the promotion has no minimum purchase.qualifying_category_ids
orqualifying_item_variation_ids
with the IDs of Catalog objects that qualify for the promotion. These fields are valid only forVISIT
andSPEND
program types. Only one of these fields can be specified for a promotion.For
qualifying_category_ids
, provide the IDs of any qualifyingCATEGORY
catalog objects. If specified, the purchase must include at least one item variation from a category in the list.For
qualifying_item_variation_ids
, provide the IDs of any qualifyingITEM_VARIATION
catalog objects. If specified, the purchase must include at least one item variation from the list.To obtain catalog object IDs, you can call ListCatalog with the
types
query parameter or SearchCatalogObjects.
Square validates the program type but doesn't check whether qualifying items conflict with any excluded items, which can optionally be defined in a
SPEND
accrual rule. Therefore, you must also check for excluded items when working withSPEND
program types. For more information, see Checking SPEND accrual rules for excluded items.
The following example request specifies an incentive
that gives double points. The available_time
field specifies that buyers can earn promotion points every Tuesday from 4 PM to 6 PM. The trigger_limit
field specifies that the promotion points can be earned a maximum of once per day (each Tuesday). The qualifying_category_ids
field specifies two categories (for example, beverages and appetizers) that qualify for the promotion.
Create loyalty promotion
The following is an example response:
{
"loyalty_promotion": {
"id": "19514729-2073-313d-81f1-dc0231660ef0",
"name": "Tuesday Happy Hour",
"incentive": {
"type": "POINTS_MULTIPLIER",
"points_multiplier_data": {
"multiplier": "2.000"
}
},
"available_time": {
"start_date": "2023-08-16",
"end_date": "2023-10-01",
"time_periods": [
"BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;UNTIL=20221001T000000;BYDAY=TU\nEND:VEVENT"
]
},
"trigger_limit": {
"times": 1,
"interval": "DAY"
},
"qualifying_category_ids": [
"XTQPYLR3IIU9C44VRCB3XD12",
"D3RYL4VRCM7CJ56IXERSTAKM"
],
"status": "ACTIVE",
"created_at": "2023-08-09T08:38:54Z",
"updated_at": "2023-08-09T08:38:54Z",
"loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
}
}
A loyalty program can have a maximum of 10 loyalty promotions with an ACTIVE
and SCHEDULED
status.
To retrieve a loyalty promotion, call RetrieveLoyaltyPromotion and provide the following information:
- The
promotion_id
path parameter with the ID of the loyalty promotion to retrieve. To get the promotion ID, call ListLoyaltyPromotions. - The
program_id
path parameter with the ID of the associated loyalty program. To get the program ID, call RetrieveLoyaltyProgram using themain
keyword.
Retrieve loyalty promotion
The following is an example response:
{
"loyalty_promotion": {
"id": "loypromo_f0f9b849-725e-378d-b810-511237e07b67",
"name": "Tuesday Happy Hour",
"incentive": {
"type": "POINTS_MULTIPLIER",
"points_multiplier_data": {
"multiplier": "2.000"
}
},
"available_time": {
"start_date": "2022-08-16",
"time_periods": [
"BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"
]
},
"trigger_limit": {
"times": 1,
"interval": "DAY"
},
"qualifying_category_ids": [
"XTQPYLR3IIU9C44VRCB3XD12",
"D3RYL4VRCM7CJ56IXERSTAKM"
],
"status": "ACTIVE",
"created_at": "2022-08-16T08:38:54Z",
"updated_at": "2022-08-16T08:38:54Z",
"loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
}
}
To learn how to determine whether a purchase qualifies to earn points from a loyalty promotion, see Calculating promotion points.
To list the loyalty promotions associated with a loyalty program, call ListLoyaltyPromotions and provide the following information:
The
program_id
path parameter with the ID of the associated loyalty program. To get the program ID, call RetrieveLoyaltyProgram using themain
keyword.The optional
status
query parameter with theACTIVE
,SCHEDULED
,ENDED
, orCANCELED
target status. By default, loyalty promotions are returned regardless of the promotion status.The optional
limit
query parameter with a maximum page size of 1 to 30 results. The default limit is 30.If the results are paged, use the
cursor
field in the response as thecursor
query parameter in your nextListLoyaltyPromotions
request.
The following example request uses status
to return only ACTIVE
promotions and limit
to specify a maximum page size of 2 results:
List loyalty promotions
The following example response contains two loyalty promotions. Results are sorted by the created_at
timestamp in descending order.
{
"loyalty_promotions": [
{
"id": "loypromo_f0f9b849-725e-378d-b810-511237e07b67",
"name": "Tuesday Happy Hour",
"incentive": {
"type": "POINTS_MULTIPLIER",
"points_multiplier_data": {
"multiplier": "2.000"
}
},
"available_time": {
"start_date": "2022-08-16",
"time_periods": [
"BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"
]
},
"trigger_limit": {
"times": 1,
"interval": "DAY"
},
"qualifying_category_ids": [
"XTQPYLR3IIU9C44VRCB3XD12",
"D3RYL4VRCM7CJ56IXERSTAKM"
],
"status": "ACTIVE",
"created_at": "2022-08-16T08:38:54Z",
"updated_at": "2022-08-16T08:38:54Z",
"loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
},
{
"id": "loypromo_e696f057-2286-35ff-8108-132241328106",
"name": "July Special",
"incentive": {
"type": "POINTS_ADDITION",
"points_addition_data": {
"points_addition": 5
}
},
"available_time": {
"start_date": "2022-07-01",
"end_date": "2022-08-01",
"time_periods": [
"BEGIN:VEVENT\nDTSTART:20220704T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=MO\nEND:VEVENT",
"BEGIN:VEVENT\nDTSTART:20220705T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=TU\nEND:VEVENT",
"BEGIN:VEVENT\nDTSTART:20220706T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=WE\nEND:VEVENT",
"BEGIN:VEVENT\nDTSTART:20220707T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=TH\nEND:VEVENT",
"BEGIN:VEVENT\nDTSTART:20220701T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=FR\nEND:VEVENT"
]
},
"trigger_limit": {
"times": 10,
"interval": "ALL_TIME"
},
"minimum_spend_amount_money": {
"amount": 2000,
"currency": "USD"
},
"status": "ACTIVE",
"created_at": "2022-06-27T15:37:38Z",
"updated_at": "2022-06-27T15:37:38Z",
"loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
}
],
"cursor": "PNEhVUKHBuTOuRIZoUcX5VQexample"
}
If no results are found, the response contains an empty object:
{}
To learn how to determine whether a purchase qualifies to earn points from a loyalty promotion, see Calculating promotion points.
To cancel a loyalty promotion, call CancelLoyaltyPromotion. You can use this endpoint to cancel an ACTIVE
promotion earlier than the end date, cancel an ACTIVE
promotion when an end date isn't specified, or cancel a SCHEDULED
promotion. Because updating a promotion isn't supported, you should also use this endpoint to cancel an ACTIVE
or SCHEDULED
promotion before you create a new one.
Provide the following information in the request:
- The
promotion_id
path parameter with the ID of the loyalty promotion to cancel. To get the promotion ID, call ListLoyaltyPromotions. - The
program_id
path parameter with the ID of the associated loyalty program. You can get the program ID from the loyalty promotion or by calling RetrieveLoyaltyProgram using themain
keyword.
Cancel loyalty promotion
Square sets the promotion status to CANCELED
, which is a terminal state.
The following is an example response that contains the canceled promotion:
{
"loyalty_promotion": {
"id": "loypromo_f0f9b849-725e-378d-b810-511237e07b67",
"name": "Tuesday Happy Hour",
"incentive": {
"type": "POINTS_MULTIPLIER",
"points_multiplier_data": {
"multiplier": "2.000"
}
},
"available_time": {
"start_date": "2022-08-16",
"time_periods": [
"BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"
]
},
"trigger_limit": {
"times": 1,
"interval": "DAY"
},
"qualifying_category_ids": [
"XTQPYLR3IIU9C44VRCB3XD12",
"D3RYL4VRCM7CJ56IXERSTAKM"
],
"status": "CANCELED",
"created_at": "2022-08-16T08:38:54Z",
"canceled_at": "2022-08-17T12:42:49Z",
"updated_at": "2022-08-17T12:42:49Z",
"loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
}
}
To qualify for points from a loyalty promotion, a purchase must first qualify for points from the base loyalty program. If the purchase qualifies for program points, use the following procedure to determine whether it also qualifies for promotion points.
Note
This procedure applies only to applications that use a custom ordering system to process orders.
If your application uses the Orders API to process orders, Square provides built-in integration for managing loyalty points. Square computes both program points and promotion points when you call AccumulateLoyaltyPoints or CalculateLoyaltyPoints and provide the ID of a Square order.
Call ListLoyaltyPromotions using the
status
query parameter to filter for theACTIVE
promotions associated with the loyalty program. Results are sorted in descending order by thecreated_at
date.Starting with the most recently created promotion, check whether the purchase meets all the following conditions. If it does not, check the next
ACTIVE
promotion in descending order by thecreated_at
date.Available time - The purchase must occur during a time period specified in the
available_time.time_periods
field. This field contains a list of iCalendar events that define the day of the week and the time of day that a promotion is available. For more information, see Available time.Minimum amount - If
minimum_spend_amount_money
is specified, the purchase amount must be greater than or equal to the specified minimum amount. If needed, retrieve the loyalty program and check thetax_mode
field of any accrual rule to determine whether taxes should be included in the purchase amount.Qualifying items - If
qualifying_item_variation_ids
orqualifying_category_ids
is specified, make sure the purchase includes at least one qualifyingITEM_VARIATION
catalog object. Only one of these fields can be specified for a promotion.For
qualifying_item_variation_ids
, the ID of at least one item variation in the purchase must match an ID specified inqualifying_item_variation_ids
.For
qualifying_category_ids
, at least one item variation in the purchase must belong to a qualifying category. Use the Catalog API to verify this condition. For example:- Call BatchRetrieveCatalogObjects and set
include_related_objects
totrue
. Forobject_ids
, specify the ID of each item variation in the purchase. - In the
related_objects
field of the response, check whether thecategory_id
of anyITEM
catalog object matches an ID specified inqualifying_category_ids
.
Category-based and item-based promotions are valid only for
VISIT
andSPEND
program types. ForSPEND
program types, also check the accrual rule to make sure the qualifying item in the purchase isn't excluded. Excluded items are defined in the optionalexcluded_item_variation_ids
andexcluded_category_ids
fields. For more information, see Checking SPEND accrual rules for excluded items.- Call BatchRetrieveCatalogObjects and set
Trigger limit - If
trigger_limit
is specified, the buyer cannot exceed this limit. If not specified, the promotion can be triggered an unlimited number of times. Note that applications that use a custom ordering system must separately record each time a loyalty account triggers a promotion to determine whether the buyer has reached the promotion's trigger limit.
If the purchase meets the promotion conditions, check the
incentive
field of the promotion to determine how to compute the promotion points:If
type
isPOINTS_MULTIPLIER
, get the multiplier from thepoints_multiplier_data.multiplier
field, which is a string representation of a decimal. For example, a purchase that qualifies for 5 program points with a points multiplier of 1.25 earns 6 total points:5 program points.
1 promotion point, calculated using
((program points x multiplier) – fractional points) - program points
.Square returns values ranging from
"1.001"
-"10.00"
in three point precision (except"10.00"
).
In this case, applications that use a custom ordering system would provide a
points
value of 6 in anAccumulateLoyaltyPoints
request and record separately that the loyalty account triggered the loyalty promotion and received 1 promotion point from the purchase.Note
If only the deprecated
points_multiplier
field is present, use its value as the multiplier.If
type
isPOINTS_ADDITION
, get the number of promotion points to add from thepoints_addition_data.points_addition
field. For example, a purchase that qualifies for 5 program points with a points addition of 3 earns 8 total points:- 5 program points.
- 3 promotion points.
In this case, applications that use a custom ordering system would provide a
points
value of 8 in anAccumulateLoyaltyPoints
request and record separately that the loyalty account triggered the loyalty promotion and received 3 promotion points from the purchase.
A purchase can earn points from one promotion only.
The following considerations apply when working with loyalty promotions:
The minimum Square version required to work with loyalty promotions is 2022-08-17. The following features have separate version requirements:
- The
qualifying_category_ids
andqualifying_item_variation_ids
fields are available in Square version 2022-08-17 or later. However, to access these fields using a Square SDK, you must use a version of the SDK that supports Square version 2022-11-16 or later. - The
points_multiplier_data.multiplier
field, which allows you to specify a decimal multiplier, is available in Square version 2023-08-16 or later. It replacespoints_multiplier
.
- The
For applications that use the Orders API to process orders, Square provides built-in integration for managing the points buyers earn from loyalty promotions. For example, when you call
AccumulateLoyaltyPoints
and provide theorder_id
, Square automatically adds the program points and promotion points to the loyalty account. Similarly, when you callCalculateLoyaltyPoints
and provide theorder_id
, Square computes both program points and promotion points.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 example, the
CalculateLoyaltyPoints
endpoint doesn't compute promotion points for these applications. In addition, theAccumulateLoyaltyPoints
endpoint doesn't provide a parameter to specify promotion points earned from a purchase, and therefore returns onlyACCUMULATE_POINTS
events (notACCUMULATE_PROMOTION_POINTS
events).These applications must compute promotion points for qualifying purchases. They must also keep track of the promotion points added to each loyalty account to be able to determine whether the buyer has reached the promotion's trigger limit. For more information, see Calculating promotion points.
A purchase can earn points for only one promotion. If a purchase qualifies for multiple promotions, Square selects the most recently created promotion that has an
ACTIVE
status. A purchase must qualify for points from the base loyalty program to be eligible for promotion points.Category-based and item-based loyalty promotions have the following requirements:
Category-based and item-based loyalty promotions are supported only for
VISIT
andSPEND
program types. ForSPEND
program types, make sure the qualifying categories or item variations for the promotion don't conflict with any exclusions defined in the accrual rule. For more information, see Checking SPEND accrual rules for excluded items.Integration with the Catalog API is required.
Category-based loyalty promotions use the
qualifying_category_ids
field to specify the IDs ofCATEGORY
catalog objects. Item-based loyalty promotions use thequalifying_item_variation_ids
field to specify the IDs ofITEM_VARIATION
catalog objects.Line items in the associated order must specify the IDs of
ITEM_VARIATION
catalog objects so that promotion points can be calculated for the purchase. For example, when creating an order using the Orders API, thecatalog_object_id
field of each line item must specify the corresponding item variation.
Loyalty promotions are available in all business locations for the Square seller and to all customers who are enrolled in the loyalty program.
A loyalty program can have a maximum of 10 loyalty promotions with an
ACTIVE
andSCHEDULED
status.Promotion points are subject to the same expiration policy as program points.