Events - List

POST /events/{merchant_id}

Description: List events for a merchant with optional filtering constraints.

---

cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/events/{merchant_id} \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "created_after": "2023-01-01T00:00:00",
  "created_before": "2023-01-31T23:59:59",
  "event_classes": [
    "payments",
    "refunds"
  ],
  "event_types": [
    "payment_succeeded"
  ],
  "is_delivered": true,
  "limit": 5,
  "object_id": "{{object_id}}",
  "offset": 0,
  "profile_id": "{{profile_id}}"
}
'

---

Example response (200)

application/json

{
  "events": [
    {
      "event_id": "evt_018e31720d1b7a2b82677d3032cab959",
      "merchant_id": "y3oqhf46pyzuxjbcn2giaqnb44",
      "profile_id": "SqB0zwDGR5wHppWf0bx7GKr1f2",
      "object_id": "QHrfd5LUDdZaKtAjdJmMu0dMa1",
      "event_type": "payment_succeeded",
      "event_class": "payments",
      "initial_attempt_id": "evt_018e31720d1b7a2b82677d3032cab959",
      "created": "2022-09-10T10:11:12Z",
      "is_delivery_successful": true
    }
  ],
  "total_count": 123
}

---

Authorizations

• api-key (string, header, required) Admin API keys allow you to perform some privileged actions such as creating a merchant account and Merchant Connector account.

---

Path Parameters

• merchant_id (string, required) The unique identifier for the Merchant Account.

---

Body (application/json)

The constraints that can be applied when listing Events.

• created_after (string | null) Filter events created after the specified time.

• created_before (string | null) Filter events created before the specified time.

• limit (integer | null) Include at most the specified number of events. Required range: x >= 0

• offset (integer | null) Include events after the specified offset. Required range: x >= 0

• object_id (string | null) Filter all events associated with the specified object identifier (Payment Intent ID, Refund ID, etc.)

• event_id (string | null) Filter all events associated with the specified event_id

• profile_id (string | null) Filter all events associated with the specified business profile ID.

• event_classes (enum[] | null) Filter events by their class. Available options:

  • payments

  • refunds

  • disputes

  • mandates

  • payouts

  • subscriptions

• event_types (enum[] | null) Filter events by their type. Available options:

  • payment_succeeded

  • payment_failed

  • payment_processing

  • payment_cancelled

  • payment_cancelled_post_capture

  • payment_authorized

  • payment_partially_authorized

  • payment_captured

  • payment_expired

  • action_required

  • refund_succeeded

  • refund_failed

  • dispute_opened

  • dispute_expired

  • dispute_accepted

  • dispute_cancelled

  • dispute_challenged

  • dispute_won

  • dispute_lost

  • mandate_active

  • mandate_revoked

  • payout_success

  • payout_failed

  • payout_initiated

  • payout_processing

  • payout_cancelled

  • payout_expired

  • payout_reversed

  • invoice_paid

• is_delivered (boolean | null) Filter all events by is_overall_delivery_successful field of the event.

---

Response (200 - application/json)

• events (object[], required) The list of events (see example response for structure).

• total_count (integer, required) Count of total events.

---

Suggest edits or report issues:

• Edit: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/event/events--list.mdx

• Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/event/events--list

Related:

• Gsm - Delete: https://api-reference.hyperswitch.io/v1/gsm/gsm--delete

• Events - Delivery Attempt List: https://api-reference.hyperswitch.io/v1/event/events--delivery-attempt-list