--- title: "SearchLoyaltyEvents" method: POST path: "/v2/loyalty/events/search" tags: ["Loyalty"] --- # SearchLoyaltyEvents `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. ## Request body - SearchLoyaltyEventsRequest — A request to search for loyalty events. - `query` LoyaltyEventQuery — Represents a query used to search for loyalty events. - `filter` LoyaltyEventFilter — The filtering criteria. If the request specifies multiple filters, the endpoint uses a logical AND to evaluate them. - `loyalty_account_filter` LoyaltyEventLoyaltyAccountFilter — Filter events by loyalty account. - `loyalty_account_id` string, required — The ID of the [loyalty account](entity:LoyaltyAccount) associated with loyalty events. - `type_filter` LoyaltyEventTypeFilter — Filter events by event type. - `types` LoyaltyEventType[], required — The loyalty event types used to filter the result. If multiple values are specified, the endpoint uses a logical OR to combine them. See [LoyaltyEventType](#type-loyaltyeventtype) for possible values - `date_time_filter` LoyaltyEventDateTimeFilter — Filter events by date time range. - `created_at` TimeRange, required — 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. - `start_at` string, nullable — A datetime value in RFC 3339 format indicating when the time range starts. - `end_at` string, nullable — A datetime value in RFC 3339 format indicating when the time range ends. - `location_filter` LoyaltyEventLocationFilter — Filter events by location. - `location_ids` string[], required — The [location](entity:Location) IDs for loyalty events to query. If multiple values are specified, the endpoint uses a logical OR to combine them. - `order_filter` LoyaltyEventOrderFilter — Filter events by the order associated with the event. - `order_id` string, required — The ID of the [order](entity:Order) associated with the event. - `limit` integer — The maximum number of results to include in the response. The last page might contain fewer events. The default is 30 events. - `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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). ## Response `200` Success - SearchLoyaltyEventsResponse — A response that contains loyalty events that satisfy the search criteria, in order by the `created_at` date. - `errors` Error[] — Any errors that occurred during the request. - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API. - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `events` LoyaltyEvent[] — The loyalty events that satisfy the search criteria. - `id` string, required — The Square-assigned ID of the loyalty event. - `type` 'ACCUMULATE_POINTS' | 'CREATE_REWARD' | 'REDEEM_REWARD' | 'DELETE_REWARD' | 'ADJUST_POINTS' | 'EXPIRE_POINTS' | 'OTHER' | 'ACCUMULATE_PROMOTION_POINTS', required — The type of the loyalty event. - `created_at` string, required — The timestamp when the event was created, in RFC 3339 format. - `accumulate_points` LoyaltyEventAccumulatePoints — Provides metadata when the event `type` is `ACCUMULATE_POINTS`. - `loyalty_program_id` string — The ID of the [loyalty program](entity:LoyaltyProgram). - `points` integer, nullable — The number of points accumulated by the event. - `order_id` string, nullable — The ID of the [order](entity:Order) for which the buyer accumulated the points. This field is returned only if the Orders API is used to process orders. - `create_reward` LoyaltyEventCreateReward — Provides metadata when the event `type` is `CREATE_REWARD`. - `loyalty_program_id` string, required — The ID of the [loyalty program](entity:LoyaltyProgram). - `reward_id` string — The Square-assigned ID of the created [loyalty reward](entity:LoyaltyReward). This field is returned only if the event source is `LOYALTY_API`. - `points` integer, required — The loyalty points used to create the reward. - `redeem_reward` LoyaltyEventRedeemReward — Provides metadata when the event `type` is `REDEEM_REWARD`. - `loyalty_program_id` string, required — The ID of the [loyalty program](entity:LoyaltyProgram). - `reward_id` string — The ID of the redeemed [loyalty reward](entity:LoyaltyReward). This field is returned only if the event source is `LOYALTY_API`. - `order_id` string — The ID of the [order](entity:Order) that redeemed the reward. This field is returned only if the Orders API is used to process orders. - `delete_reward` LoyaltyEventDeleteReward — Provides metadata when the event `type` is `DELETE_REWARD`. - `loyalty_program_id` string, required — The ID of the [loyalty program](entity:LoyaltyProgram). - `reward_id` string — The ID of the deleted [loyalty reward](entity:LoyaltyReward). This field is returned only if the event source is `LOYALTY_API`. - `points` integer, required — The number of points returned to the loyalty account. - `adjust_points` LoyaltyEventAdjustPoints — Provides metadata when the event `type` is `ADJUST_POINTS`. - `loyalty_program_id` string — The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram). - `points` integer, required — The number of points added or removed. - `reason` string, nullable — The reason for the adjustment of points. - `loyalty_account_id` string, required — The ID of the [loyalty account](entity:LoyaltyAccount) associated with the event. - `location_id` string — The ID of the [location](entity:Location) where the event occurred. - `source` 'SQUARE' | 'LOYALTY_API', required — Defines whether the event was generated by the Square Point of Sale. - `expire_points` LoyaltyEventExpirePoints — Provides metadata when the event `type` is `EXPIRE_POINTS`. - `loyalty_program_id` string, required — The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram). - `points` integer, required — The number of points expired. - `other_event` LoyaltyEventOther — Provides metadata when the event `type` is `OTHER`. - `loyalty_program_id` string, required — The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram). - `points` integer, required — The number of points added or removed. - `accumulate_promotion_points` LoyaltyEventAccumulatePromotionPoints — Provides metadata when the event `type` is `ACCUMULATE_PROMOTION_POINTS`. - `loyalty_program_id` string — The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram). - `loyalty_promotion_id` string — The Square-assigned ID of the [loyalty promotion](entity:LoyaltyPromotion). - `points` integer, required — The number of points earned by the event. - `order_id` string, required — The ID of the [order](entity:Order) for which the buyer earned the promotion points. Only applications that use the Orders API to process orders can trigger this event. - `cursor` string — The pagination cursor to be used in a subsequent request. If empty, this is the final response. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). --- [API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/revisions/6a5164284e41/schema)