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

Search for Balance-Changing Loyalty Events

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:

Note

Balance-changing activities also invoke the loyalty.account.updated and loyalty.event.created webhook events.

The following is an example LoyaltyEvent object:

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

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

    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:

    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

    Points removed

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

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

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

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

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.

Search Loyalty Events
  • 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
curl https://connect.squareupsandbox.com/v2/loyalty/events/search \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "loyalty_account_filter": {
          "loyalty_account_id": "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793"
        },
        "date_time_filter": {
          "created_at": {
            "start_at": "2020-09-01T00:00:00Z",
            "end_at": "2020-12-31T00:00:00Z"
          }
        },
        "type_filter": {
          "types": [
            "ACCUMULATE_POINTS",
            "CREATE_REWARD"
          ]
        }
      }
    },
    "limit": 10
  }'

The following is an example response.

  • 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
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
{
  "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 Seller 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

Search Loyalty Events
  • 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
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
curl https://connect.squareupsandbox.com/v2/loyalty/events/search \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "loyalty_account_filter": {
          "loyalty_account_id": "db61c1eb-c4a9-48fc-913d-92b24f9a2d7"
        },
        "date_time_filter": {
          "created_at": {
            "start_at": "2020-01-01T00:00:00Z",
            "end_at": "2020-12-31T00:00:00Z"
          }
        },
        "type_filter": {
          "types": [
            "ACCUMULATE_POINTS",
            "CREATE_REWARD",
            "REDEEM_REWARD"
          ]
        },
        "location_filter": {
          "location_ids": [
            "M3AK818160XGR",
            "LB43CCKZBPJRZ"
          ]
        }
      }
    }
  }'

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

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