Search for Balance-Changing Loyalty Events

Applies to: Loyalty API

Learn how to use the Loyalty API to list or search for events that affect the point balance of loyalty accounts.

Square Loyalty maintains a ledger of events that occur during the lifetime of a buyer's loyalty account, such as when a buyer earns points or redeems a reward. Each point balance change is recorded in the ledger.

The Loyalty API supports the following operation for working with loyalty events:

• List or search for balance-changing events

The following is an example LoyaltyEvent object:

{
  "id": "bbd1ef00-92ac-3e5f-8887-cd3c6ba29313",
  "type": "ACCUMULATE_POINTS",
  "created_at": "2020-05-07T22:31:48Z",
  "accumulate_points": {
    "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
    "points": 12,
    "order_id": "cb9LSpDgOH3rITBaZ6eIBb9ee4F"
  },
  "loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
  "location_id": "S8GWD5R9QB376",
  "source": "LOYALTY_API"
}

Each event contains the ID of the associated loyalty account, the ID of the purchase location, and the event type with a corresponding metadata object:

• An ACCUMULATE_POINTS event includes an accumulate_points object, as shown in the following excerpt:

  {
    ...
    "accumulate_points": {
      "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "points": 12,
      "order_id": "cb9LSpDgOH3rITBaZ6eIBb9ee4F"
    },
    ...
  }

  This event is invoked when points earned from an accrual rule defined for the loyalty program are added to a loyalty account.

• An ACCUMULATE_PROMOTION_POINTS event includes an accumulate_promotion_points object, as shown in the following excerpt:

  {
    ...
    "accumulate_promotion_points": {
      "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "loyalty_promotion_id": "93cc7415-ba40-42e6-80fc-dd8c798a39db",
      "points": 5,
      "order_id": "cb9LSpDgOH3rITBaZ6eIBb9ee4F"
    },
    ...
  }

  This event is invoked when points earned from a loyalty promotion are added to a loyalty account. A purchase must first qualify for program points before it can qualify for promotion points. This event type is only supported for applications that use Orders API integration.

• An ADJUST_POINTS event includes an adjust_points object, as shown in the following excerpts:

  Points added

  {
    ...
    "adjust_points": {
      "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "points": 5,
      "reason": "Lunch lottery"
    },
    ...
  }

  Points removed

  {
    ...
    "adjust_points": {
      "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "points": -3,
      "reason": "Exchanged for item of lesser value"
    },
    ...
  }

• A CREATE_REWARD event includes a create_reward object, as shown in the following excerpt:

  {
    ...
    "create_reward": {
      "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "reward_id": "b5e384d9-f873-3f08-84b6-ba4d406d5d3b",
      "points": -15
    },
    ...
  }

• A REDEEM_REWARD event includes a redeem_reward object, as shown in the following excerpt:

  {
    ...
    "redeem_reward": {
       "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
       "reward_id": "c307328e-0eae-3817-ad9f-e22187798007",
       "order_id": "YLCHbGktxbjyVDYw58mSVdfivaB"
    },
    ...
  }

• A DELETE_REWARD event includes a delete_reward object, as shown in the following excerpt:

  {
    ...
    "delete_reward": {
      "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "reward_id": "b5e384d9-f873-3f08-84b6-ba4d406d5d3b",
      "points": 15
    },
    ...
  }

• An EXPIRE_POINTS event includes an expire_points object, as shown in the following excerpt:

  {
    ...
    "expire_points": {
      "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
      "points": -5
    },
    ...
  }

• An OTHER event is invoked when Square automatically adjusts the point balance after an order is refunded. This event is returned in SearchLoyaltyEvents results, as shown in the following excerpt:

  {
    "events": [
      {
        "id": "ee70b425-43ad-3849-9526-8419be89a79a",
        "type": "OTHER",
        "created_at": "2023-05-04T22:35:26Z",
        "loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
        "location_id": "S8GWD5R9QB376",
        "source": "SQUARE",
        "other_event": {
          "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
          "points": -3
        }
      },
      ...
    ]
  }

Call SearchLoyaltyEvents endpoint to search for events that affect the point balance of loyalty accounts. Square processes any optional query filters included in the request according to a defined processing logic.

The following example request searches for ACCUMULATE_POINTS and CREATE_REWARD events for a specified loyalty account and date range. The example request also sets the limit field to specify a maximum page size of 10 results.

The following is an example response.

{
  "events": [
    {
      "id": "b200cb8c-371e-3cf0-bc7a-892f6f39052d",
      "type": "ACCUMULATE_POINTS",
      "created_at": "2020-10-17T00:17:54Z",
      "accumulate_points": {
        "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
        "points": 12,
        "order_id": "4LODyZIm7IFGgEOy7KssqDtTuaB"
      },
      "loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
      "location_id": "M8AKAD8160XGR",
      "source": "LOYALTY_API"
    },
    {
      "id": "a089eb36-0867-3b73-a2dd-10b8d3b8e632",
      "type": "CREATE_REWARD",
      "created_at": "2020-09-11T19:08:04Z",
      "redeem_reward": {
        "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
        "reward_id": "b5e384d9-f873-3f08-84b6-ba4d406d5d3b",
        "points": -15
      },
      "loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
      "location_id": "M8AKAD8160XGR",
      "source": "LOYALTY_API"
    },
    {
      "id": "ffbe24b1-74a9-39c6-b1d5-c6693b0e4fc0",
      "type": "CREATE_REWARD",
      "created_at": "2020-09-02T12:55:18Z",
      "accumulate_points": {
        "loyalty_program_id": "8031c1b2-d749-4c76-9c40-ae5472ed2e04",
        "reward_id": "998d1351-0a56-337a-aef4-502a04e11b5f",
        "points": -10
      },
      "loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793",
      "location_id": "M8AKAD8160XGR",
      "source": "LOYALTY_API"
    }
  ]
}

Results are sorted by the created_at timestamp in descending order. If no results are found, the response contains an empty object:

{}

You can use the SearchLoyaltyEvents endpoint to get status information for your buyer-facing loyalty status page. For example, the Activity section of the Square Dashboard displays information from the ledger of events.

The SearchLoyaltyEvents endpoint supports several optional query filters. Square processes any query filters included in the request as follows:

• Multiple filters in a request are evaluated using a logical AND.
• Multiple values in an array field are evaluated using a logical OR. Both type_filter and location_filter allow you to provide an array of values.

For the following example request that includes all supported query filters except order_filter, Square processes the filters as follows:

• Performs a logical AND of the following query filters:

  • date_time_filter
  • location_filter
  • loyalty_account_filter
  • type_filter

• Performs a logical OR of the values in the following array fields:

  • location_ids in the location_filter
  • types in the type_filter

For the list of supported query filters, see LoyaltyEventFilter. For the list of valid loyalty events for the type_filter field, see LoyaltyEventType.

• Loyalty API
• Manage Loyalty Points
• Manage Loyalty Rewards
• Video: Sandbox 101: Loyalty API
• API Reference: Loyalty API