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

Step 4: Redeem Points

Explore how to use the API to redeem points to earn rewards:

  • Create an order for four cups of coffee.

  • Redeem points to get a reward (a free coffee for 10 points).

  • Pay for the order.

  • Give the buyer points for the purchase. In this example, the buyer gets a discount (one free coffee) and pays for only three cups of coffee. As a result, the buyer earns three points (with item-based programs, buyers do not earn points for items already discounted by loyalty rewards).

Step 4.1: Create an order Permalink Get a link to this section

Place an order for four cups of coffee.

  1. To order coffee, you need the item variation ID for the coffee item in the catalog. If you do not have it, call ListCatalog to get a list of items in your catalog.

    List Catalog
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/catalog/list \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'
  2. Create an order for four cups of coffee by calling CreateOrder. Each coffee costs $3, so the order amount is $12.

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    curl https://connect.squareupsandbox.com/v2/orders \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "order": {
          "line_items": [
            {
              "quantity": "4",
              "catalog_object_id": "{COFFEE_ITEM_VARIATION_ID}"
            }
          ],
          "location_id": "{LOCATION_ID}"
        },
        "idempotency_key": "{UNIQUE_KEY}"
      }'

    The following is an example response:

    {
       "order":{
          "id":"I3LwAibJUA8VGZXnO3fNX8example",
          "location_id":"S8GWD5example",
          "line_items":[
             {
                "uid":"rlauAbvClDr9cnJexample",
                "catalog_object_id":"ZFPGMTKFH332UOJY3example",
                "quantity":"4",
                "name":"coffee",
                "variation_name":"",
                "base_price_money":{
                   "amount":300,
                   "currency":"USD"
                },
                "gross_sales_money":{
                   "amount":1200,
                   "currency":"USD"
                },
                "total_tax_money":{
                   "amount":0,
                   "currency":"USD"
                },
                "total_discount_money":{
                   "amount":0,
                   "currency":"USD"
                },
                "total_money":{
                   "amount":1200,
                   "currency":"USD"
                },
                "variation_total_price_money":{
                   "amount":1200,
                   "currency":"USD"
                }
             }
          ],
          "created_at":"2020-03-11T00:18:38.074Z",
          "updated_at":"2020-03-11T00:18:38.074Z",
          "state":"OPEN",
          "version":1,
          "total_tax_money":{
             "amount":0,
             "currency":"USD"
          },
          "total_discount_money":{
             "amount":0,
             "currency":"USD"
          },
          "total_tip_money":{
             "amount":0,
             "currency":"USD"
          },
          "total_money":{
             "amount":1200,
             "currency":"USD"
          },
          "total_service_charge_money":{
             "amount":0,
             "currency":"USD"
          },
          "net_amounts":{
             "total_money":{
                "amount":1200,
                "currency":"USD"
             },
             "tax_money":{
                "amount":0,
                "currency":"USD"
             },
             "discount_money":{
                "amount":0,
                "currency":"USD"
             },
             "tip_money":{
                "amount":0,
                "currency":"USD"
             },
             "service_charge_money":{
                "amount":0,
                "currency":"USD"
             }
          },
          "source":{
             "name":"Sandbox for sq0idp-MJ1Sr5Iim0hGGvAexample"
          }
       }
    }
    

Step 4.2: Show reward tier options to the buyer Permalink Get a link to this section

Your application can show the buyers a list of rewards they qualify for. To determine this list of rewards, the application can do the following:

  • Retrieve the point balance from the loyalty account of the buyer.

  • Retrieve the loyalty program, which includes the reward tier information.

  • Compare the point balance and reward tiers to determine the reward tiers the buyer qualifies for.

Step 4.2.1 Retrieve a buyer's loyalty account Permalink Get a link to this section

Call RetrieveLoyaltyAccount to retrieve the loyalty account of the buyer.

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

The following is an example response. The balance shows the available point balance.

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

Step 4.2.2 Retrieve the loyalty program Permalink Get a link to this section

Call ListLoyaltyPrograms to retrieve the loyalty program.

List Loyalty Programs
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/loyalty/programs \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response, which includes a list of the reward tiers the program offers:

{
  "programs": [
    {
      "id": "93afe66e-3a14-4be6-8d50-02755example",
      "status": "ACTIVE",
      "reward_tiers": [
        {
          "id": "9854964a-ee8b-4622-9fbe-7fcb7example",
          "points": 10,
          "name": "One free coffee",
          "definition": {
            "scope": "ITEM_VARIATION",
            "discount_type": "FIXED_PERCENTAGE",
            "percentage_discount": "100",
            "catalog_object_ids": [
              "ZFPGMTKFH332UOJY3example"
            ]
          },
          "created_at": "2020-05-11T23:33:03Z",
          "pricing_rule_reference": {
            "object_id": "78Y3HESNsJLTB2A9Iexample",
            "catalog_version": "135548example"
          }
        },
        {
          "id": "4efa3400-dca3-4464-9fe6-33bfDexample",
          "points": 15,
          "name": "One free sandwich",
          "definition": {
            "scope": "ITEM_VARIATION",
            "discount_type": "FIXED_PERCENTAGE",
            "percentage_discount": "100",
            "catalog_object_ids": [
              "HONASX6SULQC55VOWexample"
            ]
          },
          "created_at": "2020-05-11T23:33:03Z",
          "pricing_rule_reference": {
            "object_id": "ZKFKBH5IINTZLY3VAexample",
            "catalog_version": "160396example"
          }
        }
      ],
      "terminology": {
        "one": "Point",
        "other": "Points"
      },
      "location_ids": [
        "S8GWD5example"
      ],
      "created_at": "2020-05-05T23:18:07Z",
      "updated_at": "2020-05-11T23:33:03Z",
      "accrual_rules": [
        {
          "accrual_type": "ITEM_VARIATION",
          "points": 1,
          "catalog_object_id": "ZFPGMTKFH332UOJY3example"
        }
      ]
    }
  ]
}

Step 4.2.3: Determine the reward tiers to show the buyer Permalink Get a link to this section

Your application can now compare the point balance with the program's reward tiers and present applicable reward tiers to the buyer. In this example, the loyalty account has a balance of 12 points, so the buyer qualifies for reward tier 1 (redeem 10 points to get a free coffee), but does not qualify for reward tier 2 (redeem 15 points to get a free sandwich). Therefore, you need to get information about the reward tier 1 discount.

To get the discount details, use the object_id and catalog_version from the pricing_rule_reference to call the RetrieveCatalogObject endpoint in the Catalog API. Make sure to set include_related_objects to true to return all of the catalog objects that define discount details. You might also need to call to the Catalog API to get current product information. For more information, see Get discount details for the reward.

Note

The ListLoyaltyPrograms response currently also includes the deprecated definition field, which is replaced by the pricing_rule_reference field. Square recommends that you use pricing_rule_reference.

Step 4.2.4: Show the reward tiers to the buyer Permalink Get a link to this section

Your application can show the reward tier to the buyer. Assume the buyer chooses to use the reward (redeem 10 points to get a free coffee).

Step 4.3: Create a reward Permalink Get a link to this section

  1. Call CreateLoyaltyReward to apply the reward tier. In the request:

    • reward_tier_id identifies the reward tier to apply.

    • order_id identifies the order to apply.

    • loyalty_account_id identifies the buyer's loyalty account from which to take loyalty points.

    Create Loyalty Reward
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    curl https://connect.squareupsandbox.com/v2/loyalty/rewards \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "reward": {
          "loyalty_account_id": "{ACCOUNT_ID}",
          "reward_tier_id": "{REWARD_TIER_ID}",
          "order_id": "{ORDER_ID}"
        },
        "idempotency_key": "{UNIQUE_KEY}"
      }'

    The endpoint does the following:

    • Creates a reward object. Creating a reward reserves a certain number of points from the loyalty account of the buyer. These points cannot be used to redeem any other reward unless and until you delete the reward. For more information, see Loyalty rewards.

    • Updates the order as follows:

      • Adds the reward to the order (the rewards property).

      • Adds the relevant discount to order (the discounts property) and applies the discount to line items that qualify (the applied_discounts property).

      • Updates the order amount to reflect the discount.

    In response, the endpoint returns the reward created. The following is an example response:

    {
       "reward":{
          "id":"43f05faf-96b1-3169-adab-c8a6aexample",
          "status":"ISSUED",
          "loyalty_account_id":"1beb38f9-54de-4cb6-8121-718bDexample",
          "reward_tier_id":"9854964a-ee8b-4622-9fbe-7fcb7example",
          "points":10,
          "order_id":"I3LwAibJUA8VGZXnO3fNX8example",
          "created_at":"2020-05-11T23:37:06Z",
          "updated_at":"2020-05-11T23:37:06Z"
       }
    }
    
  2. Fetch the updated order.

    Call RetrieveOrder to retrieve the order and show your buyer order changes in your application UI.

    Retrieve Order
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    This is the response:

    {
      "order": {
        "id": "I3LwAibJUA8VGZXnO3fNX8example",
        "location_id": "S8GWD5example",
        "line_items": [
          {
            "uid": "C8DSCY3whA4p6W6example",
            "catalog_object_id": "ZFPGMTKFH332UOJY3example",
            "quantity": "1",
            "name": "coffee",
            "variation_name": "",
            "base_price_money": {
              "amount": 300,
              "currency": "USD"
            },
            "gross_sales_money": {
              "amount": 300,
              "currency": "USD"
            },
            "total_tax_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_discount_money": {
              "amount": 300,
              "currency": "USD"
            },
            "total_money": {
              "amount": 0,
              "currency": "USD"
            },
            "variation_total_price_money": {
              "amount": 300,
              "currency": "USD"
            },
            "applied_discounts": [
              {
                "uid": "5WxqugPnzGRiYn3example",
                "discount_uid": "AYYOZh3mL5qlIbTexample",
                "applied_money": {
                  "amount": 300,
                  "currency": "USD"
                }
              }
            ]
          },
          {
            "uid": "pISztslNZbEQbSMexample",
            "catalog_object_id": "ZFPGMTKFH332UOJY3example",
            "quantity": "3",
            "name": "coffee",
            "variation_name": "",
            "base_price_money": {
              "amount": 300,
              "currency": "USD"
            },
            "gross_sales_money": {
              "amount": 900,
              "currency": "USD"
            },
            "total_tax_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_discount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_money": {
              "amount": 900,
              "currency": "USD"
            },
            "variation_total_price_money": {
              "amount": 900,
              "currency": "USD"
            }
          }
        ],
        "discounts": [
          {
            "uid": "AYYOZh3mL5qlIbtXexample",
            "catalog_object_id": "I672Q27QOFTRK2ZWNexample",
            "name": "One free coffee",
            "percentage": "100.0",
            "applied_money": {
              "amount": 300,
              "currency": "USD"
            },
            "type": "FIXED_PERCENTAGE",
            "scope": "LINE_ITEM",
            "reward_ids": [
              "43f05faf-96b1-3169-adab-c8a6Aexample"
            ],
            "pricing_rule_id": "ZKFKBH5IINTZLY3VAexample"
          }
        ],
        "created_at": "2020-05-11T23:22:29.983Z",
        "updated_at": "2020-05-11T23:37:06.834Z",
        "state": "OPEN",
        "version": 2,
        "total_tax_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 300,
          "currency": "USD"
        },
        "total_tip_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_money": {
          "amount": 900,
          "currency": "USD"
        },
        "total_service_charge_money": {
          "amount": 0,
          "currency": "USD"
        },
        "net_amounts": {
          "total_money": {
            "amount": 900,
            "currency": "USD"
          },
          "tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "discount_money": {
            "amount": 300,
            "currency": "USD"
          },
          "tip_money": {
            "amount": 0,
            "currency": "USD"
          },
          "service_charge_money": {
            "amount": 0,
            "currency": "USD"
          }
        },
        "source": {
          "name": "Sandbox for sq0idp-FjGzHcGJQBbe_cCexample"
        },
        "rewards": [
          {
            "id": "43f05faf-96b1-3169-adab-c8a6Aexample",
            "reward_tier_id": "9854964a-ee8b-4622-9fbe-7fcb7example"
          }
        ]
      }
    }
    

    Note the following order updates:

    • The line item (line_items[]) field shows:

      • total_discount_money. Shows a $3 discount (free coffee).

      • total_money. Shows a decrease from $12 to $9.

      • applied_discounts. Shows the discount applied to the line item. It matches the applied_discounts.discount_uid match the uid of one of the discounts in the top-level discounts[] list (which identifies the list of all the discounts for the order).

    • discounts[] at the top level shows a list of discounts added for the order. In this example, there is one discount that maps the loyalty reward you created.

    The presence of the discount indicates that the reward was applied to the order. It is possible that you create a reward that does not get applied to the order. For example, you might create a reward for a free coffee, but the coffee is not in the order and the discount cannot be applied. After the order reaches the terminal state (for example the order is paid or canceled), Square deletes the reward and returns the points to the buyer's loyalty account.

Step 4.4: Take a payment Permalink Get a link to this section

Call CreatePayment to take a payment from the order.

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "cnon:card-nonce-ok",
    "amount_money": {
      "amount": 900,
      "currency": "USD"
    },
    "order_id": "{ORDER_ID}",
    "idempotency_key": "{UNIQUE_KEY}"
  }'

Step 4.5: Give buyer points for the purchase Permalink Get a link to this section

The buyer paid for the order and therefore qualifies for loyalty points. Call AccumulateLoyaltyPoints to add the points to the buyer's account. Note that order_id is the order for which the buyer is getting points. The endpoint uses the information in the order to compute the loyalty points.

Accumulate Loyalty Points
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
curl https://connect.squareupsandbox.com/v2/loyalty/accounts/{account_id}/accumulate \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accumulate_points": {
      "order_id": "{ORDER_ID}"
    },
    "location_id": "{LOCATION_ID}",
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The buyer ordered four cups of coffee and gets a discount for one cup. Therefore, the buyer gets three points for this purchase. You do not have to do any calculations. You provide the order ID in your AccumulateLoyaltyPoints request and the API uses the order to determine the loyalty points.

{
   "event":{
      "id":"efc9fc89-60e5-360a-9002-d3904example",
      "type":"ACCUMULATE_POINTS",
      "created_at":"2020-05-12T00:05:29Z",
      "accumulate_points":{
         "loyalty_program_id":"93afe66e-3a14-4be6-8d50-02755example",
         "points":3,
         "order_id":"I3LwAibJUA8VGZXnO3fNX8example"
      },
      "loyalty_account_id":"1beb38f9-54de-4cb6-8121-718bDexample",
      "location_id":"S8GWD5example",
      "source":"LOYALTY_API"
   }
}