Step 1: Set up a Loyalty Program

Applies to: Loyalty API | Catalog API

Learn how to set up a loyalty program to help increase repeat visits to a seller's business.

Square sellers can subscribe to Square Loyalty and set up a loyalty program to help increase repeat visits to their business. A loyalty program defines how buyers can earn points and redeem points for discounts. For more information, see Loyalty Program.

In this walkthrough, you create and manage resources (such as a loyalty account, catalog items, and orders) by calling Square APIs in the Square Sandbox environment. Before you begin, you need to get your Sandbox account credentials, create catalog items used for rewards, and set up a loyalty program that you can use for testing. Note that the Loyalty API cannot be used to create or update a loyalty program.

Follow these steps to get the access token and location ID used in this walkthrough.

1. Sign in to the Developer Console and open your application. If you don't have a Square account, see Get Started to learn how to create an account and an application.

2. Get your Sandbox access token:

   1. At the top of the page, in the Sandbox and Production toggle, choose Sandbox.
   2. On the Credentials page, under Sandbox Access Token, choose Show and then copy the token. All Square API requests require an access token for authorization. This personal access token grants full access to the Sandbox resources in your account.

   Important

   The Sandbox access token is a secure secret. Don't share it with anyone.

3. Get your location ID:

   1. In the left pane, choose Locations.
   2. On the Locations page, keep Default Test Account selected and copy a location ID.

   

   Note

   To retrieve location IDs programmatically, call ListLocations.

The loyalty program in this walkthrough offers a free coffee reward tier and a free sandwich reward tier. These items must be added to the product catalog before you can set up the reward tiers. For more information about Square catalogs, see Catalog API.

1. Call BatchUpsertCatalogObjects in the Catalog API to add two items to the catalog.

   Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique idempotency key.

   Batch upsert catalog objects

   cURL

   The following is an excerpt of the example response:

   {
      "objects":[
         {
            "type":"ITEM",
            "id":"WVKYFIQQVJMTHQFKKexample",
            "updated_at":"2020-03-09T03:02:50.862Z",
            "version":1583722970862,
            "is_deleted":false,
            "present_at_all_locations":true,
            "item_data":{
               "name":"Coffee",
               "variations":[
                  {
                     "type":"ITEM_VARIATION",
                     "id":"ZFPGMTKFH332UOJY3example",
                     "updated_at":"2020-03-09T03:02:50.862Z",
                     "version":1583722970862,
                     "is_deleted":false,
                     "present_at_all_locations":true,
                     "item_variation_data":{
                        "item_id":"WVKYFIQQVJMTHQFKKexample",
                        "name":"Coffee",
                        "ordinal":0,
                        "pricing_type":"FIXED_PRICING",
                        "price_money":{
                           "amount":300,
                           "currency":"USD"
                        }
                     }
                  }
               ],
               "product_type":"REGULAR"
            }
         },
         {
            "type":"ITEM",
            "id":"DZRJBEKJCFAZZMPULexample",
            "updated_at":"2020-03-09T03:02:50.862Z",
            "version":1583722970862,
            "is_deleted":false,
            "present_at_all_locations":true,
            "item_data":{
               "name":"Sandwich",
               "variations":[
                  {
                     "type":"ITEM_VARIATION",
                     "id":"HONASX6SULQC55VOWexample",
                     "updated_at":"2020-03-09T03:02:50.862Z",
                     "version":1583722970862,
                     "is_deleted":false,
                     "present_at_all_locations":true,
                     "item_variation_data":{
                        "item_id":"DZRJBEKJCFAZZMPULexample",
                        "name":"Sandwich",
                        "ordinal":0,
                        "pricing_type":"FIXED_PRICING",
                        "price_money":{
                           "amount":800,
                           "currency":"USD"
                        }
                     }
                  }
               ],
               "product_type":"REGULAR"
            }
         }
      ],
      ...
   }

2. Copy the item variation ID for Coffee in the response. Make sure to copy the id directly below the "type":"ITEM_VARIATION" line. When you place an order later, you use the item variation ID to specify the item.

Follow these steps to set up a loyalty program in the Sandbox Square Dashboard. Note that the Loyalty API cannot be used to create or update a loyalty program.

1. Open the Sandbox Square Dashboard:

   1. Return to the Developer Console home page.
   2. In the left pane, choose Sandbox test accounts.
   3. Next to Default Test Account, choose Square Dashboard.

2. In the left pane of the Sandbox Square Dashboard, choose Marketing & loyalty, and then choose Loyalty.

3. On the Build repeat business and reward your customers page, choose Get Started.

   

   You now follow a series of steps to set up your loyalty program.

   Note

   These steps assume that you're setting up a loyalty program for the first time. To change an existing program, choose Settings on the Loyalty page, and then edit the Earning Points and Redeeming Rewards settings to match the settings described in this topic.

4. On the Customize your program step, keep the default Points terminology, and then choose Next.

5. On the Select a program type step, define an accrual rule that enables customers to earn points when they purchase a specific item.

   1. Choose Item based.
   2. For Item, choose Coffee.
   3. For Points customers earn, enter 1.
   4. Choose Next.

   

6. On the Set up your rewards step, define two reward tiers that each offer a free item.

   Reward tier 1

   1. For Reward type, choose Free item.
   2. For Item, choose Coffee.
   3. For Points needed to earn this reward, enter 10.

   

   Reward tier 2

   1. Choose Create another reward.
   2. For Reward type, choose Free item.
   3. For Item, choose Sandwich.
   4. For Points needed to earn this reward, enter 15.
   5. Choose Next.

   

7. On the Review and subscribe step, review your loyalty program settings, and then choose Finish.

8. In the Subscribe to Square Loyalty dialog box, enter information for the Sandbox test credit card. This test credit card lets you sign up for Square Loyalty in the Sandbox environment for free.

   1. For Name on Card, enter a name.
   2. For Card Number, enter 4111 1111 1111 1111.
   3. For CVV, enter 111.
   4. For Expiration Date, enter a future month and year in MM/YY format.
   5. For ZIP, enter a postal code.

   

Your loyalty program is now set up. On the Loyalty page in the Square Dashboard, you can choose Settings to view or edit the program settings.