Typically events are received by server webhooks, but API calls can also be used to retrieve previous webhook events. Events are either processed or unprocessed, depending on whether your webhook endpoint has acknowledged handling of the event. To learn more about acknowledging events see Webhooks.
The webhooks system generates the event contents at the time of each transaction, subscription, or other activity. If you do not subscribe to webhooks, no webhook events are generated. Therefore, anything that happens while you do not have a webhook configuration for your Store will not have a webhook event generated, and so details of that activity will not be retrievable via the /events endpoint - even if you set up a webhook configuration after-the-fact.
For example, suppose the following are true:
- Your Store goes live on Sunday and you do not subscribe to the order.completed webhook event.
- On Monday a customer places an order.
- On Tuesday, you subscribe to the order.completed event.
- On Wednesday, a second customer places an order.
In this example, you would be able to retrieve Tuesday's order via /events, but even after you subscribe to order.completed, a call to /events would not return an order.completed event for Monday's transaction, because at the time of the transaction, there was no subscription to order.completed and so no event was generated.
You could, however, retrieve the details of Monday's order via the /orders endpoint - which does not rely on webhook event generation.
Certain modifiers are required when making a GET request to the /events endpoint of the API. Requests must include either the begin modifier to specify the unix date of the first event to be returned, or else the days modifier to specify the number of prior days' worth of events to be returned. In either case, the API will not return items more than 30 days old. Therefore, if you specify a begin date, it must be no more than 30 days past. Likewise, the number of days specified using the days parameter must not be greater than 30.
- ?days=5 - Events from last 5 days.
Limited to 25 results returned. Results will contain a "more" attribute if there are more results beyond 25. To page to additional results the timestamp of the nearest event should be fed into begin / end (narrowing the timeframe).
Get multiple events
Get processed/acknowledged events
Get unprocessed events
The response structure is nearly identical to the structure of Webhooks, except the reponse will include a type indicator that identifies the event type (e.g. order.canceled).