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.
Servers
- https://connect.squareup.com
Request headers
| Name | Type | Required | Description |
|---|---|---|---|
Content-Type |
String | Yes |
The media type of the request body.
Default value: "application/json" |
Request body fields
| Name | Type | Required | Description |
|---|---|---|---|
query |
Object | No |
Represents a query used to search for loyalty events. |
query.filter |
Object | No |
The filtering criteria. If the request specifies multiple filters, the endpoint uses a logical AND to evaluate them. |
query.filter.date_time_filter |
Object | No |
Filter events by date time range. |
query.filter.date_time_filter.created_at |
Object | Yes |
Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled. |
query.filter.date_time_filter.created_at.start_at |
String | No |
A datetime value in RFC 3339 format indicating when the time range starts. |
query.filter.date_time_filter.created_at.end_at |
String | No |
A datetime value in RFC 3339 format indicating when the time range ends. |
query.filter.order_filter |
Object | No |
Filter events by the order associated with the event. |
query.filter.order_filter.order_id |
String | Yes |
The ID of the order associated with the event. |
query.filter.type_filter |
Object | No |
Filter events by event type. |
query.filter.type_filter.types[] |
Array | Yes |
The loyalty event types used to filter the result. If multiple values are specified, the endpoint uses a logical OR to combine them. |
query.filter.location_filter |
Object | No |
Filter events by location. |
query.filter.location_filter.location_ids[] |
Array | Yes |
The location IDs for loyalty events to query. If multiple values are specified, the endpoint uses a logical OR to combine them. |
query.filter.loyalty_account_filter |
Object | No |
Filter events by loyalty account. |
query.filter.loyalty_account_filter.loyalty_account_id |
String | Yes |
The ID of the loyalty account associated with loyalty events. |
limit |
Integer | No |
The maximum number of results to include in the response. The last page might contain fewer events. The default is 30 events. |
cursor |
String | No |
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. |
How to start integrating
- Add HTTP Task to your workflow definition.
- Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
- Click Test request to test run your request to the API and see the API's response.