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

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.

Link to section
Get started with the Loyalty API

After a seller sets up a loyalty program and subscribes to Square Loyalty in the , 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.

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

Link to section
Working with loyalty promotions

For more information, see Manage Loyalty Promotions.

Link to section
Working with 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 does not 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

Note

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

Link to section
Integration with other Square APIs

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

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

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 can compute program points and promotion points for a given order ID.

    • The AccumulateLoyaltyPoints endpoint can compute program points and promotion points for a given order ID and add the points to the loyalty account of the buyer.

  • 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 . The loyalty reports in the 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 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.

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

      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.

    • 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 by choosing Accounts & Settings, Business information, 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 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 . However, 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.

  • 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 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 Slack, or reach out to your Square account manager.

Link to section
Webhooks

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

Event
Permission
Description
loyalty.account.createdLOYALTY_READA loyalty account was 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.updatedLOYALTY_READA loyalty account was updated. For example:
 •   The seller updates the phone number registered for the loyalty account using the . 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 was changed. For example, the loyalty account moved to another customer.
loyalty.account.deletedLOYALTY_READPublished 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 .
 •   The seller merges two customer profiles 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.createdLOYALTY_READA loyalty program was created. Loyalty programs can only be created from the .
loyalty.program.updatedLOYALTY_READA loyalty program was updated. Loyalty programs can only be updated from the .
loyalty.promotion.createdLOYALTY_READA loyalty promotion was created.
loyalty.promotion.updatedLOYALTY_READA loyalty promotion was canceled.
loyalty.event.createdLOYALTY_READA balance-changing event occurred. 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 the order, 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, loyalty_event, loyalty_program, or loyalty_promotion object, as shown in the following excerpt of an example loyalty.account.created notification:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
{
  "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 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 does not qualify for loyalty points.

The following are example responses based on the Square version:

  • Square version 2022-08-17 and later:

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

    For more information, including additional examples, see Accumulate loyalty points from a purchase.

  • Square version 2022-07-20 and earlier:

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

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.

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

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

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

    • 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 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: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
    Try in API Explorer

  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:

    • 1
    • 2
    • 3
    • 4
    • 5
    {
  "program": {
    // program details
  }
}

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

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    {
  "programs": [
    {
      // program details
    }
  ]
}

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 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: 2023-03-15' \
  -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}"
  }'
      Try in API Explorer

    • 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: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "mappings": [
        {
          "phone_number": "+16295551234"
        },
        {
          "phone_number": "+12085556789"
        }
      ]
    }
  }'
      Try in API Explorer

  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:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    {
   "loyalty_account":{
      "id":"716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
      "mapping": {
        "id":"6377d589-3f09-4f00-a0e8-56d7dfc1d2b5",
        "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"
   }
}

    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.

On this page