Step 3: Accumulate Loyalty Points for a Buyer

The accrual rules and loyalty promotions associated with a loyalty program define how buyers can earn points for their purchases. This step shows how you can use the integration between the Loyalty API and the Orders API to compute the points earned on a purchase and add the points to the buyer's loyalty account.

First, you create an order and take a payment. Then, you call AccumulateLoyaltyPoints to compute the points and add them to the buyer's account.

Link to section

Create an order

Link to section

Take a payment

Call CreatePayment in the Payments API to take a payment of $12 for the preceding order. In this walkthrough, you provide a Sandbox payment token for the source_id of the payment source.

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

• Replace the example value for order_id with the actual order ID.

curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "cnon:card-nonce-ok",
    "amount_money": {
      "amount": 1200,
      "currency": "USD"
    },
    "order_id": "KauTZmbuDVviwvL9L00QsYexample",
    "idempotency_key": "{UNIQUE_KEY}"
  }'

Link to section

Add points to the loyalty account

Call AccumulateLoyaltyPoints in the Loyalty API to add the points to the loyalty account.

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

• Replace the example account ID in the path with the actual loyalty account ID. If you need to get the account ID, you can call SearchLoyaltyAccounts to search by phone number or customer ID.

• Replace the example values for order_id and location_id with the actual order ID and location ID. The Loyalty API uses information in the order to compute the loyalty points.

curl https://connect.squareupsandbox.com/v2/loyalty/accounts/716cefbc-3d71-4d7c-bdc8-9c7f8example/accumulate \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accumulate_points": {
      "order_id": "KauTZmbuDVviwvL9L00QsYexample"
    },
    "location_id": "S8GWD5example",
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The following is an example response. It shows that the buyer earned 12 points from the order, based on the "Earn one point for each dollar spent" accrual rule for the loyalty program.

{
   "events": [
     {
       "id":"bbd1ef00-92ac-3e5f-8887-cd3c6example",
       "type":"ACCUMULATE_POINTS",
       "created_at":"2020-05-07T22:31:48Z",
       "accumulate_points":{
          "loyalty_program_id":"ba293138-8fbd-425d-860b-18ab3example",
          "points":12,
          "order_id":"KauTZmbuDVviwvL9L00QsYexample"
       },
       "loyalty_account_id":"716cefbc-3d71-4d7c-bdc8-9c78fexample",
       "location_id":"S8GWD5example",
       "source":"LOYALTY_API"
    }
  ]
}

A loyalty program can have loyalty promotions that enable buyers to earn points in addition to those earned from an accrual rule. For orders that qualify for promotion points, Square also returns an ACCUMULATE_PROMOTION_POINTS event. For more information, see Manage Loyalty Promotions.

For more information about this endpoint, see Accumulate loyalty points from a purchase.

Link to section

Verify the loyalty account balance

You can optionally call RetrieveLoyaltyAccount to check the loyalty point balance before or after you add points.

• Replace {ACCESS_TOKEN} with your Sandbox access token.

• Replace the example account ID with the actual loyalty account ID.

curl https://connect.squareupsandbox.com/v2/loyalty/accounts/716cefbc-3d71-4d7c-bdc8-9c7f8example \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following example response shows that 12 points were added to the balance and lifetime_points fields of the loyalty account:

{
   "loyalty_account":{
      "id":"716cefbc-3d71-4d7c-bdc8-9c78fexample",
      "mapping":{
        "id":"6377d589-3f09-4f00-a0e8-56d70example",
        "phone_number":"+14255551111",
        "created_at":"2020-01-30T00:11:58Z"
      },
      "program_id":"ba293138-8fbd-425d-860b-18ab3example",
      "balance":12,
      "lifetime_points":12,
      "customer_id":"REK96J96AS5AN2Y8Z4Hexample",
      "created_at":"2020-01-30T00:11:58Z",
      "updated_at":"2020-01-30T03:27:11Z",
      "enrolled_at":"2020-01-30T03:27:11Z"
   }
}