Learn how to use the Square Loyalty API to accumulate or adjust points for a loyalty account.
Loyalty API

Manage Loyalty Points

The point_balance field of a loyalty account represents the number of points that can be used to create a reward for the buyer.

The Loyalty API supports the following operations for working with loyalty points:

Note

To get the available point balance for a loyalty account, call RetrieveLoyaltyAccount and check the balance field.

Accumulate loyalty points from a purchase Permalink Get a link to this section

After a buyer pays for an order, call AccumulateLoyaltyPoints to add the earned points to the buyer's loyalty account. The accrual rules of a loyalty program define how buyers can earn points from purchases.

The information you provide in the AccumulateLoyaltyPoints request depends on whether you are using the Orders API to process orders. If you need to get the account ID for this request, you can call SearchLoyaltyAccounts and search by phone number or customer ID.

  • If you are using the Orders API, provide the order ID in the order_id field of your request. Square automatically computes the number of points earned from the purchase and adds the points to the loyalty account.

    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: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "accumulate_points": {
          "order_id": "cb9LSpDgOH3rITBaZ6eIBb9ee4F"
        },
        "location_id": "S8GWD509MEHCA",
        "idempotency_key": "{UNIQUE_KEY}"
      }'

    Note

    To see a typical application flow for adding earned points to a loyalty account, see Accumulate Loyalty Points for a Buyer in Loyalty Walkthrough 1.

  • If you are using a custom ordering system instead of the Orders API, first use client-side logic to compute the number of points earned from the purchase. Then specify the points in the points field of your request.

    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: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "accumulate_points": {
          "points": 7
        },
        "location_id": "S8GWD509MEHCA",
        "idempotency_key": "{UNIQUE_KEY}"
      }'

    You must use the accrual rules defined for the loyalty program to compute the points for this request. To get the accrual rules, call RetrieveLoyaltyProgram using the main keyword (or the loyalty program ID, which is specified in the loyalty account) and check the accrual_rules field. An accrual rule is represented by a LoyaltyProgramAccrualRule object that contains details about the rule. For example, the accrual_type field indicates whether the program type uses SPEND, VISIT, CATALOG, or ITEM_VARIATION accrual rules.

    For SPEND program types and VISIT program types with a minimum spend requirement, you can call CalculateLoyaltyPoints and provide the purchase amount to get the number of points the order would earn. Make sure to check the tax_mode field in the accrual rule to determine whether tax should be included in the purchase amount.

The following is an example AccumulateLoyaltyPoints response, which contains a LoyaltyEvent object of the ACCUMULATE_POINTS type. If an order ID is provided in the request, it is included in the response.

Square generates a searchable loyalty event after each change to the loyalty point balance. For more information, see Loyalty events.

Adjust loyalty points manually Permalink Get a link to this section

Call AdjustLoyaltyPoints to add or remove points from a loyalty account.

You should use this endpoint only when you need to add or remove points outside of the normal order-purchase flow. For example, you might give extra points for a special offer or deduct points for a returned item. When buyers earn points from a purchase, you should use the AccumulateLoyaltyPoints endpoint to add the earned points to the loyalty account.

  • To add points, specify a positive integer as the points value.

  • To remove points, specify a negative integer as the points value. This value must be less than or equal to the current point balance in the loyalty account.

Adjust Loyalty Points
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
curl https://connect.squareupsandbox.com/v2/loyalty/accounts/{account_id}/adjust \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "adjust_points": {
      "points": 15,
      "reason": "Sign up bonus."
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The following is an example AdjustLoyaltyPoints response, which contains a LoyaltyEvent object. Square generates a searchable loyalty event after each change to the loyalty point balance. For more information, see Loyalty events.

Calculate the loyalty points a purchase would earn Permalink Get a link to this section

For SPEND program types and VISIT program types with a minimum spend requirement, call CalculateLoyaltyPoints to get the number of points a buyer would earn from a purchase. You can show the points to the buyer while building an order. In addition, if you are using a custom ordering system instead of the Orders API, you can call this endpoint to get the points to provide to the AccumulateLoyaltyPoints endpoint.

  • If you are using the Orders API to manage orders, you provide the order_id in the request. Square calculates the points by reading the order.

    Calculate Loyalty Points
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    curl https://connect.squareupsandbox.com/v2/loyalty/programs/{program_id}/calculate \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "order_id": "RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY"
      }'
  • If you are not using the Orders API to manage orders, you provide the purchase amount in the request for the endpoint to calculate the points. The tax_mode setting of the accrual rule indicates whether taxes should be included in transaction_amount_money.

    Calculate Loyalty Points
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    curl https://connect.squareupsandbox.com/v2/loyalty/programs/{program_id}/calculate \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "transaction_amount_money": {
          "amount": 1999,
          "currency": "USD"
        }
      }'

The following is an example response:

Expiring points Permalink Get a link to this section

If a seller configures an expiration policy for a loyalty program, loyalty accounts that have a point balance include the expiring_point_deadlines field. This field contains a list of LoyaltyAccountExpiringPointDeadline objects that represent sets of points scheduled to expire at a specific time. For example:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
{
  "loyalty_account":{
    "id":"716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
    "mapping": {
      "id":"6377d589-3f09-4f00-a0e8-56d7dfc1d2b5",
      "phone_number":"+16295551234",
      "created_at":"2020-01-30T00:11:58Z"
    },
    "program_id":"8031c1b2-d749-4c76-9c40-ae5472ed2e04",
    "balance":17,
    "lifetime_points":84,
    "customer_id":"REK96J96AS5AN2Y8Z4HE2Z5NVX",
    "created_at":"2020-01-30T00:11:58Z",
    "updated_at":"2021-07-15T09:33:45ZZ",
    "enrolled_at": "2020-01-30T00:11:58Z",
    "expiring_point_deadlines":[
      {
        "points":12,
        "expires_at":"2021-11-01T09:59:00Z"
      },
      {
        "points":5,
        "expires_at":"2022-08-01T09:59:00Z"
      }
    ]
  }
}

The total number of points in the expiring_point_deadlines field equals the number of points in the balance field.

Square notifies buyers 14 days before points expire. You can use expiration information to display expiring points in your application or send custom notifications.

When loyalty points are redeemed, Square uses the points with the earliest expiration date. When points expire, Square updates the account's point balance and creates a searchable loyalty event. These actions trigger the loyalty.account.updated and loyalty.event.created webhook events.

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.