Learn how to use the Square Loyalty API to work with Square Loyalty features.
Loyalty API

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 Square Seller Dashboard. Loyalty programs help drive repeat visits to businesses by allowing customers to earn rewards from their purchases. Developers can use the Loyalty API to integrate Square Loyalty into third-party applications, such as eCommerce websites, mobile applications, and POS solutions.

Note

For feature and pricing information, see Square Loyalty and Square Loyalty Overview. For the list of countries where Square Loyalty is available, see International availability of Square Loyalty.

After a seller sets up a loyalty program and subscribes to Square Loyalty in the Seller Dashboard, you can 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:

  1. Obtain the buyer's phone number, which you need to provide (in E.164 format) when creating the loyalty account.

  2. Call RetrieveLoyaltyProgram using the main keyword to get the ID of the seller's loyalty program.

  3. Call CreateLoyaltyAccount to create a loyalty account in the loyalty program. The loyalty account is associated with a customer profile in the seller's Customer Directory. If a matching customer profile cannot be found, a new customer profile is created. For more information, see Create a loyalty account.

    After you create the loyalty account, you can enable the buyer to earn (accumulate) points from purchases and redeem points for reward discounts:

    Note

    If your application uses the Orders API, Square provides a simplified process for accumulating and redeeming loyalty points.

When you are 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. Then, you can continue with the walkthrough steps or build and send test API requests using API Explorer.

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

  • 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 does not integrate with the Orders API, you can call this endpoint to get the points to provide to the AccumulateLoyaltyPoints endpoint.

    For more information, see Manage Loyalty Points.

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

Note

You can also subscribe for webhook notifications about all loyalty events.

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

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 the optional customer ID in the CreateLoyaltyAccount request when you enroll a buyer in a loyalty program. If a customer ID is not provided, Square uses the phone number provided in the request to search the directory for a matching customer profile. If a match is not found, Square creates a new customer profile and associates it with the loyalty account. However, this process might result in the creation of multiple customer profiles for a single buyer. For example, if a customer profile without a phone number was previously created for the buyer, it would not be returned in the phone number search and Square would create another customer profile.

You can use the SearchCustomers endpoint to search for customer profiles by email address, reference ID, and other attributes.

Note

When Square creates a customer profile for a CreateLoyaltyAccount request, the creation_source field of the customer profile is set to LOYALTY.

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.

  • 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 do not 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 do not 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 does not 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.

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. Loyalty programs can include one or more accrual rules, depending on the rule type. 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, as shown in the following excerpt:

    • ITEM_VARIATION accrual rules specify an item_variation_id, which references the item variation catalog object that qualifies for points accrual, as shown in the following excerpt:

    • 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 do not qualify for points accrual, as shown in the following excerpt:

    To get information about the catalog objects used in accrual rules, you can call BatchRetrieveCatalogObjects in the Catalog API.

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

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, Ireland, 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, Ireland, 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 is not 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.

    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, and then Pricing & Subscriptions. If the subscription expires, the Loyalty page displays a banner with the message "You are not currently subscribed to Square Loyalty."

  • One loyalty program per seller account. A seller account can have only one loyalty program. However, the program can be active at multiple participating locations.

    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.

  • 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 is not 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 picked 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 Slack, or reach out to your Square Account Manager.

You can subscribe to webhook notifications for the following loyalty events. All events require LOYALTY_READ permission.

Event Description
loyalty.account.created Published when a loyalty account is created for a buyer. A loyalty account can be created using any of the following methods, which all publish this event:
  • An application calls the CreateLoyaltyAccount endpoint.
  • A buyer enrolls in the program from a Square Point of Sale application.
  • The seller enrolls a buyer using the Customer Directory.
  • The seller merges two customer accounts into one account using the Customer Directory. In this process, sellers might merge the two corresponding loyalty accounts by creating a new account and deleting the existing accounts.
loyalty.account.updated Published for any updates to an existing loyalty account. For example:
  • The seller updates the phone number registered for the loyalty account using the Seller Dashboard. For more information, see Square Loyalty FAQ.
  • Any change in the loyalty point balance, such as points added for visits, points expiration, or a manual adjustment to the point balance that a seller might perform.
  • The customer ID of the loyalty account changes. Perhaps the loyalty account moves to another customer.
loyalty.account.deleted Published when a loyalty account is deleted. The published event does not contain the customer_id that was associated with the deleted account. The following actions to delete the account can publish this event:
  • The seller deletes an account using the Seller Dashboard.
  • The seller merges two customer accounts into one account using the Customer Directory. In this process, sellers might merge the two corresponding loyalty accounts by creating a new account and deleting the existing accounts.
loyalty.program.created Published when a loyalty program is created using the Seller Dashboard.
loyalty.program.updated Published when a loyalty program is updated using the Seller Dashboard.
loyalty.event.created Square Loyalty maintains a ledger of events that occur over the lifetime of a loyalty account. Square publishes notifications for each loyalty event logged to the ledger. These loyalty events are immutable, which means they are never updated or deleted. For example, when a buyer redeems a reward and then returns it, Square publishes separate notifications for the corresponding CREATE_REWARD and DELETE_REWARD events. Similarly, Square publishes a notification for the ADJUST_POINTS event when points are deducted after a purchase that accrued points is refunded.

All notifications include the corresponding loyalty account, event, or program object, as shown in the following excerpt of an example loyalty.account.created notification:

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

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

Retired field
Rule type
Replacement field
catalog_object_idCATEGORYcategory_data.category_id
catalog_object_idITEM_VARIATIONitem_variation_data.item_variation_id
spend_amount_moneySPENDspend_data.amount_money
excluded_category_idsSPENDspend_data.excluded_category_ids
excluded_item_variation_idsSPENDspend_data.excluded_item_variation_ids
visit_minimum_amount_moneyVISITvisit_data.minimum_amount_money

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.

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

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

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

    Note

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

The ListLoyaltyPrograms endpoint is deprecated. It is 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:

  1. Update your requests. Make sure to include the main keyword in your RetrieveLoyaltyProgram request:

    Retrieve Loyalty Program
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/loyalty/programs/main \
      -H 'Square-Version: 2022-07-20' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'
  2. Update code that handles responses. You must also update your code to handle the RetrieveLoyaltyProgram response, which returns a top-level program object instead of a programs array. The following excerpts show the difference between the responses from the two endpoints.

    Excerpt from a RetrieveLoyaltyProgram response that returns a program object:

    Excerpt from a ListLoyaltyPrograms (deprecated) response that returns a programs array:

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 is not accepted in CreateLoyaltyAccount requests.

  • The type and value fields are not accepted in CreateLoyaltyAccount or SearchLoyaltyAccounts requests.

  • The mappings, type, and value fields are not returned in responses.

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

  1. Update your requests.

    • In your CreateLoyaltyAccount requests, you must use mapping and phone_number instead of mappings, type, and value, as shown in the following example:

      Create Loyalty Account
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      • 14
      curl https://connect.squareupsandbox.com/v2/loyalty/accounts \
        -X POST \
        -H 'Square-Version: 2022-07-20' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "loyalty_account": {
            "mapping": {
              "phone_number": "+16295551234"
            },
            "program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04"
          },
          "idempotency_key": "{UNIQUE_KEY}"
        }'
    • In your SearchLoyaltyAccounts requests that query by phone number, you must use phone_number instead of type and value, as shown in the following example. Note that mappings is still a valid search query filter.

      Search Loyalty Accounts
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      • 14
      • 15
      • 16
      • 17
      curl https://connect.squareupsandbox.com/v2/loyalty/accounts/search \
        -X POST \
        -H 'Square-Version: 2022-07-20' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "query": {
            "mappings": [
              {
                "phone_number": "+16295551234"
              },
              {
                "phone_number": "+12085556789"
              }
            ]
          }
        }'
  2. Update code that handles responses. You must update your code to handle returned loyalty accounts that include only the mapping and phone_number fields. The following example responses show the changes in a returned loyalty_account object.

    Example CreateLoyaltyAccount response in Square version 2021-05-13 and later:

    Example CreateLoyaltyAccount response in Square version 2021-04-21:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    {
       "loyalty_account":{
          "id":"716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
          "mappings":[
            {
              "id":"6377d589-3f09-4f00-a0e8-56d7dfc1d2b5",
              "type":"PHONE",
              "value":"+16295551234",
              "phone_number":"+16295551234",
              "created_at":"2020-01-30T00:11:58Z"
            }
          ],
          "mapping": {
            "id":"6377d589-3f09-4f00-a0e8-56d7dfc1d2b5",
            "type":"PHONE",
            "value":"+16295551234",
            "phone_number":"+16295551234",
            "created_at":"2020-01-30T00:11:58Z"
          },
          "program_id":"8031c1b2-d749-4c76-9c40-ae5472ed2e04",
          "balance":0,
          "lifetime_points":0,
          "customer_id":"REK96J96AS5AN2Y8Z4HE2Z5NVX",
          "created_at":"2020-01-30T00:11:58Z",
          "updated_at":"2020-01-30T00:11:58Z"
       }
    }
    

    Note

    The mapping field was added in Square version 2021-04-21, so earlier versions only return mappings.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.