Step 3: Accumulate Loyalty Points for a Buyer

Applies to: Loyalty API | Orders API | Payments API

Learn how to use the Loyalty API with Orders API integration to compute points earned on a purchase when adding points to a loyalty account.

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.

1. Call CreateOrder in the Orders API to create an order for one $12 item.

   • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique idempotency key.
   • Replace the example value for location_id with your actual location ID.

   Create order

   cURL

   Note

   While building the order, you can call CalculateLoyaltyPoints to get the number of points the order would earn and then show the number to the buyer.

2. Copy the order ID from the response.

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.

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.

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.

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.

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"
   }
}