Learn about the LoyaltyAccount object and how to use the Square Loyalty API to create and retrieve loyalty accounts.
Loyalty API

Create and Retrieve Loyalty Accounts

A loyalty account references the loyalty program of a Square seller and a customer profile in the seller's Customer Directory. A loyalty account also contains the point balance and a phone number mapping that associates the account with a buyer.

The Loyalty API supports the following operations for working with loyalty accounts:

Note

The point balance of the loyalty account is managed through calls to the AccumulateLoyaltyPoints, AdjustLoyaltyPoints, CreateLoyaltyReward, RedeemLoyaltyReward, DeleteLoyaltyReward endpoints. For more information, see Manage Loyalty Points or Manage Loyalty Rewards.

LoyaltyAccount object Permalink Get a link to this section

The following is an example LoyaltyAccount object:

This example loyalty account has a point balance of 10. The following fields represent key attributes of a loyalty account:

Field
Description
mappingThe phone number mapping for the account.
program_idThe ID of the Square loyalty program that the account belongs to. You can call RetrieveLoyaltyProgram to get program details.
balanceThe number of available points in the account. The point balance is managed through calls to the AccumulateLoyaltyPoints, AdjustLoyaltyPoints, CreateLoyaltyReward, RedeemLoyaltyReward, DeleteLoyaltyReward endpoints.
lifetime_pointsThe total number of points accrued during the lifetime of the account.
customer_idThe ID of the customer profile of the buyer associated with the account.
enrolled_atThe timestamp of when the buyer joined the loyalty program. If this field is not set in the CreateLoyaltyAccount request, Square populates it after the buyer's first action on their account, specifically after the first AccumulateLoyaltyPoints or CreateLoyaltyReward call made on behalf of the buyer. In first-party flows, Square populates the field when the buyer agrees to the terms of service in Square Point of Sale.

Typically, you provide this field in a CreateLoyaltyAccount request when creating a loyalty account for a buyer who already interacted with their account. For example, you would set this field when migrating accounts from an external system.
expiring_point_deadlinesThe schedule for when points in the account balance expire. This field is present only if the account has points that are scheduled to expire.

Create a loyalty account Permalink Get a link to this section

Call CreateLoyaltyAccount to create a loyalty account and enroll the buyer in a loyalty program. You must provide the following information for this request:

  • mapping and phone_number, with the buyer's phone number specified in E.164 format. You can obtain the phone number from your application flow. A given phone number can be mapped to only one loyalty account in a loyalty program.

  • program_id with the ID of the loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the main keyword.

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-05-12' \
  -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}"
  }'

Note

If you have the ID of the customer profile that is associated with the buyer, you should also specify the customer_id field in the request. Doing so can help prevent creating duplicate customer profiles in the seller's Customer Directory. For more information, see Integration with the Customers API.

After receiving the request, Square does the following:

  • If customer_id is not specified, Square checks the directory to determine whether it contains a customer profile with the same phone number. If not, Square creates a customer profile using the buyer's phone number.

  • Creates an account in the specified loyalty program.

The following is an example CreateLoyaltyAccount response:

Both balance and lifetime_points are 0 because the buyer has not yet accrued any loyalty points. Now that the account is created, the buyer can start earning points.

The phone number that you provide to create a loyalty account must use the E.164 format (for example, +16295551234). The country code of the phone number must correspond to a country where Square Loyalty is available. Otherwise, the CreateLoyaltyAccount request returns an INVALID_PHONE_NUMBER error code.

Terms of service and text notifications Permalink Get a link to this section

After a loyalty account is created, Square can contact a buyer using the phone number provided and send text messages, such as "You have a reward available." However, the buyer must agree to the terms of service before Square can send any text messages. Buyers can agree to the terms of service when they enroll in a loyalty program from a Square Point of Sale application. They can also agree on the Loyalty status page after the account is created.

When you create an account through the Loyalty API, Square cannot show the terms of service until a buyer makes a purchase through a Point of Sale application. Therefore, unless the buyer agrees to the terms of service on the Loyalty status page, they cannot receive any text messages until they agree to the terms of service when they make a purchase.

Retrieve a loyalty account Permalink Get a link to this section

Call RetrieveLoyaltyAccount if you know the ID of the loyalty account.

Retrieve Loyalty Account
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/loyalty/accounts/{account_id} \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example RetrieveLoyaltyAccount response:

If the account cannot be found, Square returns a 404 NOT_FOUND error.

List or search for loyalty accounts Permalink Get a link to this section

Call SearchLoyaltyAccounts to retrieve all loyalty accounts for the seller or to search for accounts by phone number or customer ID. A search query can contain the mappings field (to search by phone number) or the customer_ids field, but not both.

Loyalty accounts in the response are sorted by the created_at date in ascending order. If you search for phone number mappings or customer IDs, the API returns only the accounts that match the search criteria.

You can use the limit field to specify a maximum page size of 1 to 30 results. The default page size is 30.

Search by phone number Permalink Get a link to this section

To search loyalty accounts by phone number, provide a mapping that specifies the phone number in E.164 format. You can provide up to 30 mapping entries per query.

Search Loyalty Accounts
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/loyalty/accounts/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "mappings": [
        {
          "phone_number": "+16295551234"
        }
      ]
    },
    "limit": 10
  }'

Note

In a loyalty account, the phone number mapping that associates a loyalty account with a buyer can be specified using the phone_number field (preferred) or a combination of the type and value fields. When possible, you should use phone_number, as shown in the preceding example.

Search by customer ID Permalink Get a link to this section

To search loyalty accounts by customer ID, provide the customer IDs as a list of strings. You can provide up to 30 customer IDs per query.

This feature is most useful when you already have the customer ID (for example, when a buyer is logged in to your application). This way, you can retrieve loyalty accounts without prompting the buyer for a phone number.

Search Loyalty Accounts
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
curl https://connect.squareupsandbox.com/v2/loyalty/accounts/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "customer_ids": [
        "Q8002F9Y7E9JJTJ5P6JKYYEM0BC7VPG"
      ]
    },
    "limit": 10
  }'

Search without query parameters to retrieve all loyalty accounts Permalink Get a link to this section

To retrieve all loyalty accounts in the program, specify an empty query object, as shown in the following example, or omit the query field entirely:

Search Loyalty Accounts
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
curl https://connect.squareupsandbox.com/v2/loyalty/accounts/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {},
    "limit": 10
  }'

The following is an example SearchLoyaltyAccounts response:

  • 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
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
{
  "loyalty_accounts": [
    {
      "id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
      "mapping": {
        "id": "66aaab3f-da99-49ed-8b19-b87f824d73a4",
        "phone_number": "+16295551234",
        "created_at": "2020-05-08T21:44:32Z"
      },
      "program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "balance": 20,
      "lifetime_points": 50,
      "customer_id": "Q8002F9Y7E9JJTJ5P6JKYYEM0BC7VPG",
      "created_at": "2020-05-08T21:44:32Z",
      "updated_at": "2020-11-08T12:03:18Z",
      "enrolled_at": "2020-05-08T21:44:48Z"
    },
    {
      "id": "452ea896-f36e-4c5c-95d5-e5aa727b9b2c",
      "mapping": {
        "id": "cbde1ec6-96df-40d4-8019-af9a4fa893ed",
        "phone_number": "+14255554670",
        "created_at": "2020-05-29T04:04:11Z"
      },
      "program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "balance": -10,
      "lifetime_points": 10,
      "customer_id": "6E51KR0B3GVAKE0GP0HAMH6BT0",
      "created_at": "2020-05-29T04:04:11Z",
      "updated_at": "2020-06-20T11:19:28Z",
      "enrolled_at": "2020-05-29T04:56:02Z"
    }
  ]
}

Your application should be able to handle loyalty accounts that have a negative point balance (balance is less than 0). This might occur if a seller makes a manual adjustment or as a result of a refund or exchange.

Results are sorted by created_at in ascending order. If no results are found, the response contains an empty object:

Related topics Permalink Get a link to this section

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