Loyalty API Overview

Square sellers who use Square Point of Sale (POS) or Square Online can subscribe to Square Loyalty and set up a loyalty program in the Seller Dashboard. Loyalty programs help drive repeat visits to businesses by allowing customers to earn points that can be redeemed for future discounts. Developers can use the Loyalty API to integrate Square Loyalty into third-party applications, such as eCommerce websites, mobile applications, and POS solutions.

Link to section

Get started with the Loyalty API

After a seller sets up a loyalty program and subscribes to Square Loyalty in the Seller Dashboard, you can create loyalty accounts to enroll buyers in the loyalty program. Then, buyers can start earning points from purchases and redeeming points for reward discounts.

To enroll a buyer in a loyalty program, you create a loyalty account for the buyer:

When you're ready to try calling the Loyalty API, you can watch the Sandbox 101: Loyalty API video or follow step 1 in walkthrough 1 or walkthrough 2 to set up a loyalty program in the Square Sandbox and subscribe to Square Loyalty for free. You can then continue with the walkthrough steps or build and send test API requests using API Explorer.

Link to section

Supported Loyalty API operations

You can use Loyalty API endpoints to perform the following operations:

Link to section

Working with loyalty programs

• RetrieveLoyaltyProgram - Get information about a loyalty program, such as the program ID used to create a loyalty account and the program's accrual rules and reward tiers.

  For more information, see Retrieve a Loyalty Program.

Link to section

Working with loyalty promotions

• CreateLoyaltyPromotion - Create a loyalty promotion that enables buyers to earn extra points.

• RetrieveLoyaltyPromotion - Get information about a loyalty promotion, such as the promotion status, incentive, and available time.

• ListLoyaltyPromotions - List the loyalty promotions associated with a loyalty program.

• CancelLoyaltyPromotion - Cancel a loyalty promotion.

For more information, see Manage Loyalty Promotions.

Link to section

Working with loyalty accounts

• CreateLoyaltyAccount - Create a loyalty account that enrolls a buyer in a loyalty program.

• RetrieveLoyaltyAccount - Get information about a loyalty account, such as the available point balance and associated customer ID.

• SearchLoyaltyAccounts - List all loyalty accounts, or search accounts by one or more phone number mappings or customer IDs.

  For more information, see Create and Retrieve Loyalty Accounts.

Link to section

Working with loyalty points

• AccumulateLoyaltyPoints - Add points that a buyer earned from a purchase to a loyalty account.

• AdjustLoyaltyPoints - Add or remove points from a loyalty account outside of the normal order-purchase flow. For example, you might call this endpoint to give extra points for a special offer or remove points after an item is returned.

• CalculateLoyaltyPoints - Get the number of points a buyer would earn from a purchase, which you can display while building the order. If your application doesn't integrate with the Orders API, you can call this endpoint to help compute the points to provide to the AccumulateLoyaltyPoints endpoint.

  For more information, see Manage Loyalty Points.

Link to section

Working with loyalty rewards

• CreateLoyaltyReward - Issue a loyalty reward, which removes the required points from the loyalty account balance and holds them in reserve until the reward is redeemed or deleted.

• RedeemLoyaltyReward - Redeem a loyalty reward, which permanently removes the points from the loyalty account balance. If your application integrates with the Orders API, Square automatically calls this endpoint after the order is paid.

• RetrieveLoyaltyReward - Get information about a loyalty reward.

• SearchLoyaltyRewards - List all loyalty rewards, or search rewards by a loyalty account ID and then optionally by a reward status.

• DeleteLoyaltyReward - Delete a reward that was issued but not redeemed.

  For more information, see Manage Loyalty Rewards.

Link to section

Working with balance-changing loyalty events

• SearchLoyaltyEvents - List all events that resulted in a change to the loyalty point balance, or search events by a loyalty account ID, date range, and other supported attributes.

  For more information, see Search for Balance-Changing Loyalty Events.

Link to section

Integration with other Square APIs

Loyalty programs have built-in integration with the following Square APIs:

• Customers API

• Orders API

• Catalog API

Link to section

Integration with the Customers API

All loyalty accounts have a customer_id field that associates the account with a customer profile in the seller's Customer Directory. This association enables integration features such as searching loyalty accounts by customer ID and accessing loyalty activity from the customer's Loyalty Summary card in the directory.

When possible, you should provide a customer_id in the CreateLoyaltyAccount request when you enroll buyers in a loyalty program. If customer_id isn't provided, Square uses the phone number provided in the request to search the directory for a matching customer profile. If a match isn't found, Square creates a new customer profile and associates it with the loyalty account. However, this process can result in duplicate profiles if the buyer's customer profile doesn't have a matching phone number. To avoid creating duplicate customer profiles, call SearchCustomers to search customer profiles by another identifying attribute, such as email address or reference ID before creating the account.

Link to section

Integration with the Orders API

The Loyalty API is integrated with the Orders API and you should leverage this in your applications. Some of the benefits are:

• A simplified point accrual flow. The following Loyalty API endpoints let you easily compute the points earned on orders created using the Orders API.

  • The CalculateLoyaltyPoints endpoint computes program points and promotion points for the specified order.

  • The AccumulateLoyaltyPoints endpoint computes program points and promotion points for the specified order and add the points to the loyalty account of the buyer.

  Square also automatically adjusts loyalty points when an order is refunded, depending on the program type and refund type. For more information, see Customer and Refunds in Square Loyalty FAQ.

• A simplified reward redemption flow. The Loyalty API provides the CreateLoyaltyReward endpoint to create a reward and turn the reward into appropriate discounts by automatically updating the order. The Loyalty Walkthrough 1 and Loyalty Walkthrough 2 examples show how the integration works.

  The Orders API provides an added benefit when working with multiple discounts on an order. The pricing engine that Square provides can aggregate multiple discounts from various sources. Without the Orders API, you need to write code to accomplish this task.

• Useful reporting in the Seller Dashboard. The loyalty reports in the Seller Dashboard provide useful metrics about how the loyalty program is working:

  • The Visits report uses order data to show the number of visits by first-time and repeat loyalty buyers and the average visits by loyalty and non-loyalty buyers.

  • The Sales report shows the sales amount and average amount spent by loyalty and non-loyalty buyers.

    The Seller Dashboard also shows the Top Customers report.

Depending on the program type, your development costs might be higher if you don't use the Orders API for order processing. However, the following loyalty programs are easy to implement without using the Orders API:

• A loyalty program that offers visit-based accrual - Consider this VISIT accrual rule: "Earn one point for every visit, with a minimum purchase of $10." In this case, you can add points to the buyer's account with minimal code. You don't need itemized orders. For example, suppose a buyer pays $15 for an order. You can use the CalculateLoyaltyPoints endpoint to compute loyalty points and then call AccumulateLoyaltyPoints to add the points to the buyer's account.

• A loyalty program that offers amount-spent accrual - Consider this SPEND accrual rule: "Earn one point for each dollar spent." You can use the CalculateLoyaltyPoints endpoint to compute loyalty points and then call AccumulateLoyaltyPoints to add the points to the loyalty account of the buyer. This doesn't require matching any order line items to compute the loyalty points.

Note that the accrual logic used to calculate the number of points earned depends on the tax-mode setting of the VISIT or SPEND accrual rule. If you use the Orders API, these amounts are known and the points are computed appropriately without the need of additional code.

Link to section

Integration with the Catalog API

A loyalty program contains accrual rules and reward tiers, both of which are integrated with the Catalog API.

• Accrual rules - An accrual rule defines how buyers can earn points from the base loyalty program. The type of accrual rule used by the program determines the program type. For example, a Category-based program type is configured using one or more CATEGORY accrual rules.

  The following rule types integrate with the Catalog API:

  • CATEGORY accrual rules specify a category_id, which references the CATEGORY catalog object that qualifies for points accrual.

  • ITEM_VARIATION accrual rules specify an item_variation_id, which references the ITEM_VARIATION catalog object that qualifies for points accrual.

  • SPEND accrual rules can optionally specify excluded_category_ids and excluded_item_variation_ids, which contain the IDs of any CATEGORY and ITEM_VARIATION catalog objects that don't qualify for points accrual.

  For more information, see Accrual rules.

• Reward tiers - A reward tier defines how buyers can redeem points for discounts. Loyalty programs can include one or more reward tiers. For example, a reward tier might represent a reward such as "Redeem 10 points for 10% off your entire purchase." A loyalty reward tier uses PRICING_RULE, DISCOUNT, and PRODUCT_SET catalog objects to define the discount details for a reward. For more information, see Get discount details for a reward tier.

• Loyalty promotions - Loyalty promotions enable buyers to earn extra points in addition to points earned from the base loyalty program. Category-based and item-based promotions specify the IDs of CATEGORY and ITEM_VARIATION catalog objects that qualify for promotion points.

Link to section

Requirements and limitations

The following requirements and limitations apply when integrating the Square loyalty program in applications using the Loyalty API. For more information about loyalty programs, including pricing information, see Square Loyalty Overview and Loyalty Program Overview.

• International availability of Square Loyalty - Square Loyalty is currently available in the following countries: Australia, Canada, France, Ireland, Japan, Spain, the United Kingdom, and the United States. To be eligible to subscribe to Square Loyalty, the seller's Square account must be activated in a country where Square Loyalty is available. In addition, the country code of the phone number used to create a loyalty account must correspond to a country where Square Loyalty is available.

  Square applies the following accrual logic for SPEND program types and VISIT program types that have a minimum spend requirement:

  • Before-tax versus after-tax purchase amounts - By default, the country of the seller account determines whether points accrual is based on the before-tax or after-tax purchase amount:

    • Seller accounts activated in Canada and the United States use the before-tax purchase amount.

    • Seller accounts activated in Australia, France, Ireland, Japan, Spain, and the United Kingdom use the after-tax purchase amount.

    Sellers can also configure the before-tax or after-tax points accrual setting on the Settings page in the Loyalty section of the Seller Dashboard.

    In a LoyaltyProgram object, this setting corresponds to the tax_mode field of SPEND or VISIT accrual rules.

  • Before-tip purchase amounts - For all countries, points are accrued based on purchase amounts before any added tip.

• Square Loyalty subscription - The seller must have an active Square Loyalty subscription to use loyalty features. If the seller isn't an active subscriber, calls to CreateLoyaltyAccount, AdjustLoyaltyPoints, and AccumulateLoyaltyPoints return a 404 NOT_FOUND error similar to the following example. Calls to other Loyalty API endpoints might also fail.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9

  {
    "errors": [
      {
        "code": "NOT_FOUND",
        "detail": "Merchant does not have a loyalty program",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }
  

  To get the subscription status, call RetrieveLoyaltyProgram and check the status field of the returned loyalty program. Sellers can also check their subscription status in the Seller Dashboard by choosing Accounts & Settings, Business information, and then Pricing & Subscriptions. If the subscription expires, the Loyalty page displays a banner with the message "You aren't currently subscribed to Square Loyalty."

• One loyalty program per seller account - A Square seller account can have only one loyalty program. However, the program can be active at multiple participating locations. Sellers can have up to 10 ACTIVE and SCHEDULED loyalty promotions which are available in all active locations. Application must use Square version 2022-08-17 or later to work with loyalty promotions.

  Note that sellers can enable or disable whether buyers can accrue loyalty points for in-person purchases on a given device.

• Loyalty programs are read-only with the Loyalty API - The Loyalty API cannot be used to create or modify loyalty program settings. Sellers can configure their loyalty program only on the Loyalty page of the Seller Dashboard. Creating a program invokes the loyalty.program.created webhook event and updating the program invokes a loyalty.program.updated event. Note that the Loyalty API can be used to create and manage loyalty promotions for a loyalty program.

• Limited support for loyalty promotions for custom ordering applications - 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 more information, see Considerations.

• Limited support for managing loyalty accounts with the Loyalty API - The Loyalty API lets you create loyalty accounts and manage points and rewards for loyalty accounts, but it cannot be used to update account settings or delete accounts. However, sellers can change the phone number for an account or delete an account from the customer's Loyalty Summary tile in the Seller Dashboard. Note the following:

  • Changing the phone number replaces the existing LoyaltyAccount.mapping object with a new mapping that contains the updated phone number. This action invokes the loyalty.account.updated webhook event. The phone number assigned to the associated customer profile isn't affected.

  • Deleted loyalty accounts are permanently removed from the seller account and don't appear in SearchLoyaltyAccounts results. This action invokes the loyalty.account.deleted webhook event.

• OAuth permissions - Applications that use OAuth require the LOYALTY_READ or LOYALTY_WRITE permission to perform any Loyalty API actions. For more information, see OAuth Overview and Permissions Reference for Loyalty.

• Reward redemption - The following considerations apply when redeeming rewards:

  • While redeeming multiple rewards of different tiers on the same order is supported, redeeming multiple rewards of the same tier on the same order isn't supported.

  • When redeeming multiple rewards on the same order, only one reward can apply to each line item. Consequently, redeeming multiple whole purchase rewards leads to the highest discount being used and others being ignored.

  • If a reward tier references an invalid catalog item, or another condition prevents the Loyalty API from converting a reward tier, calls to RetrieveLoyaltyProgram and ListLoyaltyPrograms (deprecated) return an UNSUPPORTED_LOYALTY_REWARD_TIER error. If this occurs, contact Developer Support, join our Discord community, or reach out to your Square account manager.

Link to section

Webhooks

You can subscribe to webhook notifications for the following loyalty events.

All notifications include the corresponding loyalty_account, loyalty_event, loyalty_program, or loyalty_promotion object, as shown in the following excerpt of an example loyalty.account.created notification:

{
  "merchant_id": "6QJXJGB6AZFN7",
  "type": "loyalty.account.created",
  "event_id": "45957f82-1e7e-42a3-9532-a4e787c3344c",
  "created_at": "2021-07-13T17:37:11Z",
  "data": {
    "type": "loyalty_account",
    "id": "dd17bfc8-178a-456c-ba4e-dae5813d429f",
    "object": {
      "loyalty_account": {
        // loyalty account fields
      }
    }
  }
}

For more information about subscribing to events and validating notifications, see Square Webhooks Overview.

Link to section

Migration notes

The following migration notes apply to the Loyalty API.

Link to section

Deprecated points_multiplier field

The points_multiplier field in the LoyaltyPromotionIncentivePointsMultiplierData object is deprecated and replaced by the new multiplier field. This change adds support for decimal multipliers of up to three precision points. Multipliers are used in loyalty promotions that define a POINTS_MULTIPLIER incentive type.

Deprecated in version: 2023-08-16
Retired in version: TBD

To update your CreateLoyaltyPromotion requests when defining a POINTS_MULTIPLIER incentive, replace points_multiplier with multiplier and provide a string representation of a decimal. Decimal notation is optional for multipliers that represent integer values.

The following examples represent a POINTS_MULTIPLIER incentive that earns double points, based on the Square version:

• Square version 2023-08-16 and later:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8

  ...
  "incentive": {
    "type": "POINTS_MULTIPLIER",
    "points_multiplier_data": {
      "multiplier": "2"             // or "2.0", "2.00", "2.000"
    }
  },
  ...
  

  If the deprecated points_multiplier is provided in a CreateLoyaltyPromotion request, Square returns both the points_multiplier and multiplier fields in the response. The multiplier value is returned in three point precision (except "10.00").

  In addition, applications that don't integrate with the Orders API (and therefore use client-side logic to calculate promotion points) must change their logic before the points_multiplier field is retired. Specifically, you need to support decimal multipliers and convert the multiplier string value to a decimal. For more information, see Calculating promotion points.

• Square version 2023-07-20 and earlier:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8

  ...
  "incentive": {
    "type": "POINTS_MULTIPLIER",
    "points_multiplier_data": {
      "points_multiplier": 2
    }
  },
  ...
  

Link to section

Deprecated event field in AccumulateLoyaltyPoints response

The event field in an AccumulateLoyaltyPoints response is deprecated and replaced by the new events field. This change allows the endpoint to return the ACCUMULATE_POINTS and ACCUMULATE_PROMOTION_POINTS events when a Square order specified in the request qualifies for points from the base loyalty program and an associated loyalty promotion.

Deprecated in version: 2022-08-17
Retired in version: TBD

To migrate to version 2022-08-17, update your code to handle an events field in the AccumulateLoyaltyPoints response:

• If your application uses Orders API integration, the new events field can contain a single ACCUMULATE_POINTS event or an ACCUMULATE_POINTS event and an ACCUMULATE_PROMOTION_POINTS event. Applications that integrate with the Orders API specify the ID of a Square order in the order_id of the AccumulateLoyaltyPoints request.

• If your application uses a custom ordering system, the new events field always contains a single ACCUMULATE_POINTS event. The ACCUMULATE_PROMOTION_POINTS event is only supported for applications that use Orders API integration.

Square continues to return an empty object when a purchase doesn't qualify for loyalty points.

The following are example responses based on the Square version:

• Square version 2022-08-17 and later:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17

  {
    "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"
      }
    ]
  }
  

• Square version 2022-07-20 and earlier:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15

  {
    "event": {
      "id": "ee46aafd-1af6-3695-a385-276e2ef0be26",
      "type": "ACCUMULATE_POINTS",
      "created_at": "2020-05-08T21:41:12Z",
      "accumulate_points": {
        "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd",
        "points": 6,
        "order_id": "RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY"
      },
      "loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd",
      "location_id": "P034NEENMD09F",
      "source": "LOYALTY_API"
    }
  }
  

Link to section

Retired LoyaltyProgramAccrualRule type-specific fields

The following LoyaltyProgramAccrualRule fields are retired and replaced by fields in new type-specific objects, as shown in the following table:

Retired in version: 2022-01-20

These new and retired fields are read-only from the Loyalty API, which cannot be used to create or update loyalty programs. Loyalty programs can be configured and managed only in the Seller Dashboard.

To migrate from the retired fields, you must update code that parses the accrual rules in a RetrieveLoyaltyProgram and ListLoyaltyPrograms (deprecated) response. Specifically, for the accrual_rules field of the loyalty program, your code must handle the new category_data, item_variation_data, spend_data, or visit_data fields and related data. These fields are shown in the following examples.

• Example CATEGORY accrual rules. The new category_data.category_id field replaces the retired catalog_object_id field.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18

  ...
  "accrual_rules": [
    {
      "accrual_type": "CATEGORY",
      "points": 1,
      "category_data": {
        "category_id": "7ZERJKO5PVYXCVUHV2JCZ2UG"
      }
    },
    {
      "accrual_type": "CATEGORY",
      "points": 3,
      "category_data": {
        "category_id": "FQKAOJE5C4FIMF5A2URMLW6V"
      }
    }
  ]
  ...
  

• Example ITEM_VARIATION accrual rules. The new item_variation_data.item_variation_id field replaces the retired catalog_object_id field.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18

  ...
  "accrual_rules": [
    {
      "accrual_type": "ITEM_VARIATION",
      "points": 1,
      "item_variation_data": {
        "item_variation_id": "CBZXBUVVTYUBZGQO44RHMR6B"
      }
    },
    {
      "accrual_type": "ITEM_VARIATION",
      "points": 2,
      "item_variation_data": {
        "item_variation_id": "EDILT24Z2NISEXDKGY6HP7XV"
      }
    }
  ]
  ...
  

• Example SPEND accrual rule with the following new fields:

  • spend_data.amount_money replaces the retired spend_amount_money field.

  • spend_data.excluded_category_ids (optional) replaces the retired excluded_category_ids field.

  • spend_data.excluded_item_variation_ids (optional) replaces the retired excluded_item_variation_ids field.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23

  ...
  "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"
      }
    }
  ]
  ...
  

• Example VISIT accrual rule. The new visit_data.minimum_amount_money field (optional) replaces the retired visit_minimum_amount_money field.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15

  ...
  "accrual_rules": [
    {
      "accrual_type": "VISIT",
      "points": 1,
      "visit_data": {
        "minimum_amount_money": {
          "amount": 500,
          "currency": "USD"
        },
        "tax_mode": "BEFORE_TAX"
      }
    }
  ]
  ...
  
  Note

  The SPEND and VISIT accrual rule examples include the tax_mode field that was added in Square version 2022-01-20.

Link to section

Deprecated ListLoyaltyPrograms endpoint

The ListLoyaltyPrograms endpoint is deprecated. It's replaced by calling the RetrieveLoyaltyProgram endpoint with the main keyword. Both endpoints are used to return the single loyalty program for a seller account.

Deprecated in version: 2021-05-13
Retired in version: TBD

To migrate to the RetrieveLoyaltyProgram endpoint, do the following:

Link to section

Retired mappings, type, and value fields

A loyalty account mapping is used to associate the loyalty account with a buyer by phone number. The following mapping-related fields are retired:

• In the LoyaltyAccount object, the mappings field is retired and replaced by mapping.

• In the LoyaltyAccountMapping object, the type and value fields are retired and replaced by phone_number.

Retired in version: 2021-05-13

In Square version 2021-05-13 and later:

• The mappings field isn't accepted in CreateLoyaltyAccount requests.

• The type and value fields aren't accepted in CreateLoyaltyAccount or SearchLoyaltyAccounts requests.

• The mappings, type, and value fields aren't returned in responses.

To migrate to the required mapping implementation, do the following:

Link to section

See also

• Loyalty Program Overview

• Loyalty API Example Walkthrough 1

• Loyalty API Example Walkthrough 2

• Square Loyalty Pricing

• Video: Sandbox 101: Loyalty API

• API Reference: Loyalty