Events v2

Events are generated to keep you informed of activity in your business account. APIs in the /v2 namespace generate thin events which have small, unversioned payloads that include a reference to the ID of the object that has changed. The Events v2 API returns these new thin events. Retrieve the event object for additional data about the event. Use the related object ID in the event payload to fetch the API resource of the object associated with the event. Comparatively, events generated by most API v1 include a versioned snapshot of an API object in their payload.

Learn more about calling API v2 endpoints.

Endpoints

GET/v2/core/events/:id

GET/v2/core/events

POST/v2/core/event_destinations/:id/ping

The Event object v2

Attributes

idstring
Unique identifier for the event.

objectstring, value is "v2.core.event"
String representing the object’s type. Objects of the same type share the same value of the object field.

changesnullable object
Before and after changes for the primary related object.

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

datanullable object
Additional data about the event.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring
The type of the event.

The Event object

{
  "id": "evt_test_65RCjj4EqW1sabcjs2Z16RCMoNQdSQkOWvfL6L5uU2K40u",
  "object": "v2.core.event",
  "context": null,
  "created": "2024-09-26T17:46:22.134Z",
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {
          "code": "meter_event_no_customer_defined",
          "error_count": 1,
          "sample_errors": [
            {
              "error_message": "Customer mapping key stripe_customer_id not found in payload.",
              "request": {
                "identifier": "cb447754-6880-45c2-8f2f-ef19b6ce81e9"
              }
            }
          ]
        }
      ]
    },
    "validation_end": "2024-09-26T17:46:20.000Z",
    "validation_start": "2024-09-26T17:46:10.000Z"
  },
  "livemode": false,
  "reason": null,
  "related_object": {
    "id": "mtr_test_61RCjiqdTDC91zgip41IqPCzPnxqqSVc",
    "type": "billing.meter",
    "url": "/v1/billing/meters/mtr_test_61RCjiqdTDC91zgip41IqPCzPnxqqSVc"
  },
  "type": "v1.billing.meter.error_report_triggered"
}

Retrieve an Event v2

Retrieves the details of an event.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
Unique identifier for the object.

Returns

Response attributes

idstring
Unique identifier for the event.

objectstring, value is "v2.core.event"
String representing the object’s type. Objects of the same type share the same value of the object field.

changesnullable object
Before and after changes for the primary related object.

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

datanullable object
Additional data about the event.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring
The type of the event.

Error Codes

404not_found

The resource wasn’t found.

GET /v2/core/events/:id

curl https://api.stripe.com/v2/core/events/evt_test_65RCjj4EqW1sabcjs2Z16RCMoNQdSQkOWvfL6L5uU2K40u \
  -H "Authorization: Bearer sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz" \
  -H "Stripe-Version: 2026-02-25.preview"

Response

{
  "id": "evt_test_65RCjj4EqW1sabcjs2Z16RCMoNQdSQkOWvfL6L5uU2K40u",
  "object": "v2.core.event",
  "context": null,
  "created": "2024-09-26T17:46:22.134Z",
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {
          "code": "meter_event_no_customer_defined",
          "error_count": 1,
          "sample_errors": [
            {
              "error_message": "Customer mapping key stripe_customer_id not found in payload.",
              "request": {
                "identifier": "cb447754-6880-45c2-8f2f-ef19b6ce81e9"
              }
            }
          ]
        }
      ]
    },
    "validation_end": "2024-09-26T17:46:20.000Z",
    "validation_start": "2024-09-26T17:46:10.000Z"
  },
  "livemode": false,
  "reason": null,
  "related_object": {
    "id": "mtr_test_61RCjiqdTDC91zgip41IqPCzPnxqqSVc",
    "type": "billing.meter",
    "url": "/v1/billing/meters/mtr_test_61RCjiqdTDC91zgip41IqPCzPnxqqSVc"
  },
  "type": "v1.billing.meter.error_report_triggered"
}

List Events v2

List events, going back up to 30 days.

Learn more about calling API v2 endpoints.

Parameters

createdobject
Set of filters to query events within a range of created timestamps.

limitinteger
The page size.

object_idstring
Primary object ID used to retrieve related events.

pagestring
The requested page.

typesarray of strings
An array of up to 20 strings containing specific event names.

Returns

Response attributes

dataarray of objects
List of events.

next_page_urlnullable string
URL to fetch the next page of the list. If there are no more pages, the value is null.

previous_page_urlnullable string
URL to fetch the previous page of the list. If there are no previous pages, the value is null.

GET /v2/core/events

curl -G https://api.stripe.com/v2/core/events \
  -H "Authorization: Bearer sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz" \
  -H "Stripe-Version: 2026-02-25.preview" \
  -d object_id=mtr_test_61RCjiqdTDC91zgip41IqPCzPnxqqSVc

Response

{
  "data": [
    {
      "id": "evt_test_65RCjj4EqW1sabcjs2Z16RCMoNQdSQkOWvfL6L5uU2K40u",
      "object": "v2.core.event",
      "context": null,
      "created": "2024-09-26T17:46:22.134Z",
      "data": {
        "developer_message_summary": "There is 1 invalid event",
        "reason": {
          "error_count": 1,
          "error_types": [
            {
              "code": "meter_event_no_customer_defined",
              "error_count": 1,
              "sample_errors": [
                {
                  "error_message": "Customer mapping key stripe_customer_id not found in payload.",
                  "request": {
                    "identifier": "cb447754-6880-45c2-8f2f-ef19b6ce81e9"
                  }
                }
              ]
            }
          ]
        },
        "validation_end": "2024-09-26T17:46:20.000Z",
        "validation_start": "2024-09-26T17:46:10.000Z"
      },
      "livemode": false,
      "reason": null,
      "related_object": {
        "id": "mtr_test_61RCjiqdTDC91zgip41IqPCzPnxqqSVc",
        "type": "billing.meter",
        "url": "/v1/billing/meters/mtr_test_61RCjiqdTDC91zgip41IqPCzPnxqqSVc"
      },
      "type": "v1.billing.meter.error_report_triggered"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

Ping an Event Destination v2

Send a ping event to an event destination.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
Identifier for the event destination to ping.

Returns

Response attributes

idstring
Unique identifier for the event.

objectstring, value is "v2.core.event"
String representing the object’s type. Objects of the same type share the same value of the object field.

changesnullable object
Before and after changes for the primary related object.

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

datanullable object
Additional data about the event.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring
The type of the event.

Error Codes

404not_found

The resource wasn’t found.

POST /v2/core/event_destinations/:id/ping

curl -X POST https://api.stripe.com/v2/core/event_destinations/evt_test_65RM8sQH2oXnebF5Rpc16RJyfa2xSQLHJJh1sxm7H0KI92/ping \
  -H "Authorization: Bearer sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz" \
  -H "Stripe-Version: 2026-02-25.preview"

Response

{
  "id": "evt_test_65RM8sQH2oXnebF5Rpc16RJyfa2xSQLHJJh1sxm7H0KI92",
  "object": "v2.core.event",
  "context": null,
  "created": "2024-10-22T16:26:54.063Z",
  "data": null,
  "livemode": false,
  "reason": null,
  "related_object": {
    "id": "ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6",
    "type": "event_destination",
    "url": "/v2/core/event_destinations/ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6"
  },
  "type": "v2.core.event_destination.ping"
}

Events v2

The Event object v2

Attributes

idstring

objectstring, value is "v2.core.event"

changesnullable object

contextnullable string

createdtimestamp

datanullable object

livemodeboolean

reasonnullable object

related_objectnullable object

typestring

Retrieve an Event v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.core.event"

changesnullable object

contextnullable string

createdtimestamp

datanullable object

livemodeboolean

reasonnullable object

related_objectnullable object

typestring

List Events v2

Parameters

createdobject

limitinteger

object_idstring

pagestring

typesarray of strings

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

Ping an Event Destination v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.core.event"

changesnullable object

contextnullable string

createdtimestamp

datanullable object

livemodeboolean

reasonnullable object

related_objectnullable object

typestring