Applies to: Events API | OAuth API | Square Webhooks | Webhook Subscriptions API
Learn how the Events API can be used to search for and retrieve Square API events.
The Events API lets you search for and retrieve Square API events occurring within a 28-day period. You can use the API to manage event data when real-time responses to data changes aren't necessary.
The Events API serves as a disaster recovery and reconciliation mechanism for missed webhook events due to server outages, misconfigured webhook subscriptions, network errors, and similar issues. By allowing access to and review of past events, the Events API helps you maintain data integrity and continuity during disruptions.
- You can only retrieve events that occurred within the past 28 days.
- You can search for all event types listed in Events, except for the deprecated V1 PAYMENT_UPDATED event type.
Because Square events are owned by the application and not by any one seller, you cannot use OAuth access tokens with the Events API. You can only access the Events API using your personal access token.
The Events API uses OAuth on the backend to authenticate whether your application is authorized to receive specific events. Your application must have OAuth access to an event at the time it occurs to see it in the search results. For example, with OAuth access to payment permissions of a seller's account, you can use the Events API to search for the payment.created event for that seller using your personal access token.
For more information about OAuth processes, see OAuth Best Practices.
The Events API is a pull-based alternative to webhooks. In addition to receiving real-time event notifications, you can periodically poll the Events API to retrieve events. The API gives you access to the event data directly, removing the need to rely on a notification URL.
While the Events API allows you to manage event data in scenarios where real-time notifications aren't needed, it doesn't replace webhooks entirely. Instead, it complements the Webhook Subscriptions API by providing a pull-based method to reconcile real-time events with historical ones (in order).
Use case examples for the Events API include the following:
- Direct access to event data - Retrieve event data directly without needing a notification URL.
- Disaster recovery - If you miss events due to server downtime or network issues, you can use the Events API to recover them.
- Data reconciliation - Regularly poll the Events API to ensure that your system's event data stays current and consistent with Square's records.
- Audit and reporting - Access historical event data for audit trails, reporting, and analytics purposes without relying on real-time event notifications.
Using the Events API involves the following steps:
- Authenticate your requests - Obtain and use your personal access token to authenticate the Events API.
- Define polling intervals - Determine and set intervals for polling the Events API to retrieve new events.
- Handle retrieved events - Develop logic to process retrieved events based on the event's
created_attimestamp.
The Events API includes one primary endpoint, SearchEvents, along with three supporting endpoints: EnableEvents, DisableEvents, and ListEventTypes.
| Endpoint | Action |
|---|---|
| SearchEvents | To search for Square API events that occurred within a 28-day period. You can filter events based on event types, seller IDs, location IDs, and created_at parameters. For a complete list of filters that you can use, see SearchEventsFilter. By default, Square sorts events by their creation time using the created_at timestamp. For a list of sort criteria that you can use, see SearchEventsSort. |
| EnableEvents | To enable events to make them searchable. Before you can search for events, you must first enable them using the EnableEvents endpoint. You cannot enable individual event types. The EnableEvents endpoint doesn’t have a request or response body. |
| DisableEvents | To disable events to prevent them from being searchable. All events are disabled by default. You must enable events to make them searchable. You cannot disable individual event types. Disabling events for a specific time period prevents them from being searchable, even if you re-enable them later. The DisableEvents endpoint doesn’t have a request or response body. |
| ListEventTypes | To list event types that you can search for. |
The SearchEvents request searches for events with the type labor.shift.created and limits the number of results to three. To retrieve events beyond these three, send your original query along with the pagination cursor provided in the response as shown in the following example.
Search events
If you don’t specify an event_type filter, the response includes all events. For a complete list of event types that you can filter by, see Webhook Events.
You can filter events by seller ID. For example, you can retrieve all events for a single seller or a group of sellers. You can also filter events by their creation time using the created_at timestamp or the location_id. Note that the created_at timestamp is inclusive. For a complete list of filters that you can use, see SearchEventsFilter.
The following example shows using the ListEventTypes endpoint to list the event types that you can search for:
List event types