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 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:

1. Call RetrieveLoyaltyProgram to retrieve the base loyalty program.

2. In the returned loyalty program, if the accrual_rules field contains an accrual rule of the SPEND type, check whether excluded_category_ids or excluded_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:

   1. Call BatchRetrieveCatalogObjects and set include_related_objects to true. For object_ids, specify the ID of each item variation.
   2. In the related_objects field of the response, check the category_id of the ITEM catalog object that corresponds to the item variation. Note that the corresponding item is referenced in the item variation's item_id field.

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 the main 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 for type and provide points_multiplier_data with the multiplier 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 for type and provide points_addition_data with the points_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 the time_periods field. Square uses this event data to populate the start_date and (optional) end_at fields and to set the loyalty promotion to the ACTIVE or SCHEDULED status. For more information, see Available time.

  • trigger_limit with the times and interval 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 or qualifying_item_variation_ids with the IDs of Catalog objects that qualify for the promotion. These fields are valid only for VISIT and SPEND program types. Only one of these fields can be specified for a promotion.

    • For qualifying_category_ids, provide the IDs of any qualifying CATEGORY 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 qualifying ITEM_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 with SPEND 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.

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 the main keyword.

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 the main keyword.

• The optional status query parameter with the ACTIVE, SCHEDULED, ENDED, or CANCELED 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 the cursor query parameter in your next ListLoyaltyPromotions request.

The following example request uses status to return only ACTIVE promotions and limit to specify a maximum page size of 2 results:

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 the main keyword.

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.

1. Call ListLoyaltyPromotions using the status query parameter to filter for the ACTIVE promotions associated with the loyalty program. Results are sorted in descending order by the created_at date.

2. 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 the created_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 the tax_mode field of any accrual rule to determine whether taxes should be included in the purchase amount.

   • Qualifying items - If qualifying_item_variation_ids or qualifying_category_ids is specified, make sure the purchase includes at least one qualifying ITEM_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 in qualifying_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:

     1. Call BatchRetrieveCatalogObjects and set include_related_objects to true. For object_ids, specify the ID of each item variation in the purchase.
     2. In the related_objects field of the response, check whether the category_id of any ITEM catalog object matches an ID specified in qualifying_category_ids.

     Category-based and item-based promotions are valid only for VISIT and SPEND program types. For SPEND 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 optional excluded_item_variation_ids and excluded_category_ids fields. For more information, see Checking SPEND accrual rules for excluded items.

   • 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.

3. If the purchase meets the promotion conditions, check the incentive field of the promotion to determine how to compute the promotion points:

   • If type is POINTS_MULTIPLIER, get the multiplier from the points_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 an AccumulateLoyaltyPoints 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 is POINTS_ADDITION, get the number of promotion points to add from the points_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 an AccumulateLoyaltyPoints 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 and qualifying_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 replaces points_multiplier.

• 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 the order_id, Square automatically adds the program points and promotion points to the loyalty account. Similarly, when you call CalculateLoyaltyPoints and provide the order_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, the AccumulateLoyaltyPoints endpoint doesn't provide a parameter to specify promotion points earned from a purchase, and therefore returns only ACCUMULATE_POINTS events (not ACCUMULATE_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 and SPEND program types. For SPEND 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 of CATEGORY catalog objects. Item-based loyalty promotions use the qualifying_item_variation_ids field to specify the IDs of ITEM_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, the catalog_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 and SCHEDULED status.

• Promotion points are subject to the same expiration policy as program points.

• Loyalty API Overview
• Retrieve a Loyalty Program
• Create and Retrieve Loyalty Accounts
• Manage Loyalty Points
• Search for Balance-Changing Loyalty Events
• API Reference: Loyalty