Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Loyalty API: Walkthrough 2

Step 1: Set up a Loyalty Program

Step 1.1: Prepare Permalink Get a link to this section

To prepare for the walkthrough, you:

  • Review Sandbox testing considerations.

  • Gather account information.

  • Add items to the catalog.

  • Set up the Square loyalty program.

The following steps provide the details.

Step 1.1.1: Square Sandbox testing considerations Permalink Get a link to this section

You test the sample walkthrough in the Square Sandbox environment. After creating a loyalty program, you need a phone number to set up a loyalty account. In the Sandbox, you provide a Sandbox phone number, instead of a real phone number, using the following format:

+1<valid-area-code>555<any-four-digits>

For example, +14255551111. For more information and other Sandbox values, see Sandbox Test Values.

Step 1.1.2: Gather account information Permalink Get a link to this section

You need your access token and location ID. You use the access token to authenticate requests and you need your location ID when you create an order using the Orders API. Follow these steps to gather account information for your Sandbox environment:

  1. Sign in to the Developer Dashboard.

  2. Open an application, which provides you with the credentials you use. If you do not have an application, you might need to create one.

  3. Get Sandbox credentials:

    1. You can toggle between the Sandbox and Production account. Choose Sandbox.

    2. On the Credentials page, copy the token from Sandbox Access Token.

  4. Get a location ID:

    1. Choose Locations in the left navigation.

    2. On the Locations page, choose an ID from Location ID.

Step 1.1.3: Add items to the catalog Permalink Get a link to this section

The loyalty program in this exercise offers free coffee and sandwiches as rewards. These items must be in the product catalog in the seller account before you can set up the loyalty program. The following example uses the Catalog API to add these items to the catalog:

  1. Call BatchUpsertCatalogObject to add two items to the seller catalog. In the request, the idempotency key must be unique. For more information, see Idempotency.

    curl https://connect.squareupsandbox.com/v2/catalog/batch-upsert \
      -X POST \
      -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -d '{
       "idempotency_key":"{{UNIQUE_KEY}}",
       "batches":[
          {
             "objects":[
                {
                   "type":"ITEM",
                   "id":"#temp-id-for-coffee",
                   "present_at_all_locations":true,
                   "item_data":{
                      "name":"coffee",
                      "variations":[
                         {
                            "type":"ITEM_VARIATION",
                            "id":"#coffee-variation-temp-value",
                            "present_at_all_locations":true,
                            "item_variation_data":{
                               "pricing_type":"FIXED_PRICING",
                               "price_money":{
                                  "amount":300,
                                  "currency":"USD"
                               }                        }
                         }
                      ]
                   }
                },
                {
                   "type":"ITEM",
                   "id":"#temp-id-for-sandwich",
                   "present_at_all_locations":true,
                   "item_data":{
                      "name":"sandwich",
                      "variations":[
                         {
                            "type":"ITEM_VARIATION",
                            "id":"#sandwich-variation-temp-value",
                            "present_at_all_locations":true,
                            "item_variation_data":{
                               "pricing_type":"FIXED_PRICING",
                               "price_money":{
                                  "amount":600,
                                  "currency":"USD"
                               }
                            }
                         }
                      ]
                   }
                }
             ]
          }
       ]
    }'
    

    The following is the example response:

    {
       "objects":[
          {
             "type":"ITEM",
             "id":"WVKYFIQQVJMTHQFKKLBWDWP2",
             "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":"ZFPGMTKFH332UOJY3WKFVVLZ",
                      "updated_at":"2020-03-09T03:02:50.862Z",
                      "version":1583722970862,
                      "is_deleted":false,
                      "present_at_all_locations":true,
                      "item_variation_data":{
                         "item_id":"WVKYFIQQVJMTHQFKKLBWDWP2",
                         "name":"",
                         "ordinal":0,
                         "pricing_type":"FIXED_PRICING",
                         "price_money":{
                            "amount":300,
                            "currency":"USD"
                         }
                      }
                   }
                ],
                "product_type":"REGULAR"
             }
          },
          {
             "type":"ITEM",
             "id":"DZRJBEKJCFAZZMPULXJMWADM",
             "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":"HONASX6SULQC55VOWLYPFAV2",
                      "updated_at":"2020-03-09T03:02:50.862Z",
                      "version":1583722970862,
                      "is_deleted":false,
                      "present_at_all_locations":true,
                      "item_variation_data":{
                         "item_id":"DZRJBEKJCFAZZMPULXJMWADM",
                         "name":"",
                         "ordinal":0,
                         "pricing_type":"FIXED_PRICING",
                         "price_money":{
                            "amount":600,
                            "currency":"USD"
                         }
                      }
                   }
                ],
                "product_type":"REGULAR"
             }
          }
       ],
       "id_mappings":[
          {
             "client_object_id":"#temp-id-for-coffee",
             "object_id":"WVKYFIQQVJMTHQFKKLBWDWP2"
          },
          {
             "client_object_id":"#temp-id-for-sandwich",
             "object_id":"DZRJBEKJCFAZZMPULXJMWADM"
          },
          {
             "client_object_id":"#coffee-variation-temp-value",
             "object_id":"ZFPGMTKFH332UOJY3WKFVVLZ"
          },
          {
             "client_object_id":"#sandwich-variation-temp-value",
             "object_id":"HONASX6SULQC55VOWLYPFAV2"
          }
       ]
    }
    
  2. Write down the item variation IDs for each of these items. When you place an order in following steps, you specify the items by using the item variation IDs.

Step 1.2: Set up a loyalty program Permalink Get a link to this section

Use the following steps to open the Seller Dashboard in the Sandbox. If you have an existing program, modify the program to set the earning points rule and reward tiers as explained.

  1. Open the Seller Dashboard in the Sandbox.

    1. Sign in to the Seller Dashboard.

    2. In the Sandbox Test Accounts section, choose Open for Default Test Account. This opens the Seller Dashboard where you create your loyalty program.

  2. Create a loyalty program.

    1. If this is your first time setting up a loyalty program, an introductory Loyalty Program page opens. Choose Get Started on the page. Otherwise, choose Loyalty in the left navigation, and then choose Settings. walk-through-1-first-time

      You now follow a series of steps to setup a loyalty program.

    2. On the Loyalty Program: Earning Points page, add the following rule in the Earning Points dialog box: "Earn one point for each coffee purchased", and then choose Continue. walk-through-2-earn-points

    3. On the Loyalty Program: Earning Points page, choose Next.

    4. On the Loyalty Program: Redeeming Rewards" step, choose Create a New Reward.

    5. In the New Reward dialog box,

      • Set the following values to create a reward: "10 points earns a free coffee". walk-through-2-new-reward-1

      • Choose Add a New Reward to add a second reward tier: "15 points earns a free sandwich". walk-through-2-new-reward-2

    6. On the Loyalty Program: Redeeming Rewards step, choose Next.

    7. On the Loyalty Program: Review Program page, review the loyalty program information (Earning Points and Redeeming Rewards section), and then choose Next.

    8. On the Loyalty Program: Start Free Trial page, choose Start Free Trial. This opens the Subscribe to Square Loyalty dialog box.

    9. In the dialog box, provide the following fake credit card number that Square provides for the Sandbox environment.
      walk-through-1-subscribe For more information about these sandbox values, see Sandbox Test Values.

    10. On the Loyalty Program page, choose Continue to Overview.

You have now created and subscribed to the Square loyalty program.

Previous

< Set up a Loyalty Program

Next

Enroll a Buyer >