Applies to: Loyalty API | Customers API
Learn about the LoyaltyAccount object and how to use the Square Loyalty API to 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, and DeleteLoyaltyReward endpoints. For more information, see Manage Loyalty Points or Manage Loyalty Rewards.
The following is an example LoyaltyAccount object:
{
"id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
"mapping": {
"id": "66aaab3f-da99-49ed-8b19-b87f824d73a4",
"phone_number": "+16295551234",
"created_at": "2020-04-16T21:44:32Z"
},
"program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
"balance": 10,
"lifetime_points": 20,
"customer_id": "Q8002F9Y7E9JJTJ5P6JKYYEM0BC7VPG",
"created_at": "2020-04-16T21:44:32Z",
"updated_at": "2020-05-08T09:10:50Z",
"enrolled_at": "2020-05-01T22:01:15Z"
}This example loyalty account has a point balance of 10. The following fields represent key attributes of a loyalty account:
| Field | Description |
|---|---|
mapping | The phone number mapping for the account. |
program_id | The ID of the Square loyalty program that the account belongs to. You can call RetrieveLoyaltyProgram to get program details. |
balance | The number of available points in the account. The point balance is managed through calls to the AccumulateLoyaltyPoints, AdjustLoyaltyPoints, CreateLoyaltyReward, RedeemLoyaltyReward, DeleteLoyaltyReward endpoints. |
lifetime_points | The total number of points accrued during the lifetime of the account. |
customer_id | The ID of the customer profile of the buyer associated with the account. |
enrolled_at | The timestamp of when the buyer joined the loyalty program. If this field isn't 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_deadlines | The schedule for when points in the account balance expire. This field is present only if the account has points that are scheduled to expire. |
The Loyalty API cannot be used to update account settings or delete accounts. However, sellers can change the phone number for an account or delete an account in the Square Dashboard. For more information, see Limited support for managing loyalty accounts with the Loyalty API.
Call CreateLoyaltyAccount to create a loyalty account and enroll the buyer in a loyalty program. You must provide the following information for this request:
mappingandphone_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_idwith the ID of the loyalty program. To get the program ID, call RetrieveLoyaltyProgram using themainkeyword.
Create loyalty account
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_idisn't 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:
{
"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"
}
}Both balance and lifetime_points are 0 because the buyer hasn't 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.
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.
Call RetrieveLoyaltyAccount if you know the ID of the loyalty account.
Retrieve loyalty account
The following is an example RetrieveLoyaltyAccount response:
{
"loyalty_account": {
"id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
"mapping": {
"id": "66aaab3f-da99-49ed-8b19-b87f824d73a4",
"phone_number": "+16295551234",
"created_at": "2020-04-16T21:44:32Z"
},
"program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
"balance": 10,
"lifetime_points": 20,
"customer_id": "Q8002F9Y7E9JJTJ5P6JKYYEM0BC7VPG",
"created_at": "2020-04-16T21:44:32Z",
"updated_at": "2020-05-08T09:10:50Z",
"enrolled_at": "2020-05-01T22:01:15Z"
}
}If the account cannot be found, Square returns a 404 NOT_FOUND error.
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 200 results. The default page size is 30.
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
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.
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
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
The following is an example SearchLoyaltyAccounts response:
{
"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 as a result of a points adjustment, refund, or exchange.
Results are sorted by created_at in ascending order. If no results are found, the response contains an empty object:
{}