Step 2: Enroll a Buyer in a Loyalty Program

Applies to: Loyalty API

Learn how to enroll a buyer in a loyalty program so they can accumulate and redeem points.

To enroll a buyer in a loyalty program, you create a loyalty account and provide the program ID and buyer's phone number. You can obtain the buyer's phone number from your application flow. For this walkthrough, you provide a test phone number that uses the format +1<valid-area-code>555<any-four-digits> and works in the Square Sandbox.

1. Call RetrieveLoyaltyProgram using the main keyword to retrieve the loyalty program in the seller's account.

   Replace {ACCESS_TOKEN} with your Sandbox access token.

   Retrieve loyalty program

   cURL

2. Copy the program ID from the response.

1. Call CreateLoyaltyAccount to create a loyalty account.

   • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string. A unique idempotency key guarantees that Square processes a request only once.
   • Replace the example value for program_id with the actual program ID.

   Note that the mapping field references the buyer by phone number.

   Create loyalty account

   cURL

   After receiving the request, Square does the following:

   • Checks the seller's Customer 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 response:

   {
      "loyalty_account":{
         "id":"1beb38f9-54de-4cb6-8121-718bDexample",
         "mapping":{
           "id":"e27de0ff-e56f-450d-95cb-a49a4example",
           "phone_number":"+14155551234",
           "created_at":"2020-05-11T22:55:18Z"
         },
         "program_id":"93afe66e-3a14-4be6-8d50-02755example",
         "balance":0,
         "lifetime_points":0,
         "customer_id":"Q80035RNBEZ4WYTB1P9PTAMTexample",
         "created_at":"2020-05-11T22:55:18Z",
         "updated_at":"2020-05-11T22:55:18Z"
      }
   }

2. Copy the ID of the new loyalty account from the response. Make sure to copy the id for the loyalty account, not for the mapping.

   The response also includes other account information, such as the customer_id of the associated customer profile. Note that both balance and lifetime_points are 0 because the buyer hasn't yet accrued any loyalty points.

   Now that you have the account ID, you can use it to access the loyalty account. For example, you can call RetrieveLoyaltyAccount.

   Retrieve loyalty account

   cURL