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.

Did you know?

Check out the Sandbox 101: Loyalty API video, which shows how to set up a loyalty program in the Sandbox, create a loyalty account, and then add and redeem loyalty points using steps that are similar to this walkthrough.

Link to section

Create an order

  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


    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.

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.

Create payment

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.

Accumulate 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.

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.

Did you know?

A searchable loyalty event is generated when the loyalty point balance changes. For more information, see Search for Balance-Changing Loyalty Events.

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.

Retrieve loyalty account

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