Manage Loyalty Promotions

Applies to: Loyalty API | Orders API | Catalog API

Learn about the LoyaltyPromotion object and how to use the Square Loyalty API to manage loyalty promotions.

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.

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 or qualifying_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 the DTSTART 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. Only FREQ=WEEKLY is supported. To specify an end date, use the UNTIL keyword. To schedule a promotion to run 1 day only, omit the RRULE field.

After the promotion is created:

• Square sets the start_date to the earliest date specified. When the start_date is reached, Square sets the status of the promotion to ACTIVE.
• If end dates are specified, Square sets the end_date to the latest date specified. When the end_date is reached, Square sets the status to ENDED. 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