• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Search loyalty events

POST /v2/loyalty/events/search

Searches for loyalty events.

A Square loyalty program maintains a ledger of events that occur during the lifetime of a buyer's loyalty account. Each change in the point balance (for example, points earned, points redeemed, and points expired) is recorded in the ledger. Using this endpoint, you can search the ledger for events.

Search results are sorted by created_at in descending order.

Permissions
LOYALTY_READ
Guide
Search loyalty events Try in API Explorer

Request Body

Example code
Name Description
query
LoyaltyEventQuery

A set of one or more predefined query filters to apply when searching for loyalty events. The endpoint performs a logical AND to evaluate multiple filters and performs a logical OR on arrays
that specifies multiple field values.
limit
integer (32-bit)

The maximum number of results to include in the response. The last page might contain fewer events. The default is 30 events.

Min 1 Max 30
cursor
string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. For more information, see Pagination.

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
events
LoyaltyEvent [ ]

The loyalty events that satisfy the search criteria.
cursor
string

The pagination cursor to be used in a subsequent request. If empty, this is the final response. For more information, see Pagination.

Examples

You are viewing an old version of the API
POST /v2/loyalty/events/search
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/loyalty/events/search \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "order_filter": {
          "order_id": "PyATxhYLfsMqpVkcKJITPydgEYfZY"
        }
      }
    },
    "limit": 30
  }'
Response JSON 
{
  "events": [
    {
      "id": "c27c8465-806e-36f2-b4b3-71f5887b5ba8",
      "type": "ACCUMULATE_POINTS",
      "created_at": "2020-05-08T22:01:30Z",
      "accumulate_points": {
        "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd",
        "points": 5,
        "order_id": "PyATxhYLfsMqpVkcKJITPydgEYfZY"
      },
      "loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd",
      "location_id": "P034NEENMD09F",
      "source": "LOYALTY_API"
    },
    {
      "id": "e4a5cbc3-a4d0-3779-98e9-e578885d9430",
      "type": "REDEEM_REWARD",
      "created_at": "2020-05-08T22:01:15Z",
      "redeem_reward": {
        "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd",
        "reward_id": "d03f79f4-815f-3500-b851-cc1e68a457f9",
        "order_id": "PyATxhYLfsMqpVkcKJITPydgEYfZY"
      },
      "loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd",
      "location_id": "P034NEENMD09F",
      "source": "LOYALTY_API"
    },
    {
      "id": "5e127479-0b03-3671-ab1e-15faea8b7188",
      "type": "CREATE_REWARD",
      "created_at": "2020-05-08T22:00:44Z",
      "create_reward": {
        "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd",
        "reward_id": "d03f79f4-815f-3500-b851-cc1e68a457f9",
        "points": -10
      },
      "loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd",
      "source": "LOYALTY_API"
    }
  ]
}