Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Loyalty

  • Create loyalty account

  • Search loyalty accounts

  • Retrieve loyalty account

  • Accumulate loyalty points

  • Adjust loyalty points

  • Search loyalty events

  • Retrieve loyalty program

  • Calculate loyalty points

  • List loyalty promotions

  • Create loyalty promotion

  • Retrieve loyalty promotion

  • Cancel loyalty promotion

  • Create loyalty reward

  • Search loyalty rewards

  • Delete loyalty reward

  • Retrieve loyalty reward

  • Redeem loyalty reward

  • Webhooks

  • loyalty.account.created

  • loyalty.account.deleted

  • loyalty.account.updated

  • loyalty.event.created

  • loyalty.program.created

  • loyalty.program.updated

  • loyalty.promotion.created

  • loyalty.promotion.updated

<- Loyalty API

Loyalty API

All versions ->

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
Link to section

Request body

Example code

Link to section

query

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.

Link to section

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
Link to section

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.

Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

events

The loyalty events that satisfy the search criteria.

Link to section

cursor

string

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

Link to section

Examples

All versions ->

POST /v2/loyalty/events/search
curl https://connect.squareup.com/v2/loyalty/events/search \ -X POST \ -H 'Square-Version: 2026-11-18' \ -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" } ] }