Events
The events endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.
The event object
| Field | Type | About |
|---|
id | string | An id that starts ev_. |
object | string | Always "event". |
type | enum | One of customer.created, customer.updated, payment.created, payment.updated, payment.requires_action, payment.requires_capture, payment.succeeded, payment.failed, payment.canceled, refund.created, refund.succeeded, refund.failed, subscription.created, subscription.updated, subscription.canceled, dispute.created, dispute.updated, checkout.session.completed, checkout.session.expired. |
api_version | enum | One of 2026-11-06. |
created | integer | Unix seconds. |
livemode | boolean | |
data | object | |
data.object_version | integer | More than 0. |
data.object | Customer or Payment or Refund or Subscription or Dispute or Checkout session | |
{
"id": "ev_1a2B3c4D5e6F7g8H9i0J1k2L",
"object": "event",
"type": "payment.succeeded",
"api_version": "2026-11-06",
"created": 1762473600,
"livemode": false,
"data": {
"object_version": 1,
"object": {
"id": "py_1a2B3c4D5e6F7g8H9i0J1k2L",
"object": "payment",
"amount": 4999,
"amount_capturable": 0,
"amount_captured": 4999,
"amount_refunded": 0,
"currency": "USD",
"capture_method": "automatic",
"status": "succeeded",
"store": "st_1a2B3c4D5e6F7g8H9i0J1k2L",
"customer": "cu_1a2B3c4D5e6F7g8H9i0J1k2L",
"payment_method": "pm_1a2B3c4D5e6F7g8H9i0J1k2L",
"subscription": null,
"disputed": false,
"description": "Order 1001",
"statement_descriptor": "Example Shop",
"failure_code": null,
"decline_code": null,
"next_action": null,
"metadata": {
"order": "1001"
},
"livemode": false,
"created": 1762473600
}
}
}
GET /v1/events
List events, newest first, each with its object as it is now.
- Scope
events:read- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Not used. A read changes nothing.
- Answers
- 200 with a list of Event, newest first.
Parameters
| Name | In | Type | Required | About |
|---|
type | query | enum | Optional | One of customer.created, customer.updated, payment.created, payment.updated, payment.requires_action, payment.requires_capture, payment.succeeded, payment.failed, payment.canceled, refund.created, refund.succeeded, refund.failed, subscription.created, subscription.updated, subscription.canceled, dispute.created, dispute.updated, checkout.session.completed, checkout.session.expired. |
limit | query | integer | Optional | At least 1. Up to 100. Defaults to 10. |
cursor | query | string | Optional | |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Errors
Examples
curl "https://api.kashupay.com/v1/events?limit=3" \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const list = await kashu("GET", "/v1/events?limit=3");
console.log(list.has_more);
GET /v1/events/{id}
Retrieve an event, with its object as it is now.
- Scope
events:read- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Not used. A read changes nothing.
- Answers
- 200 with the Event.
Parameters
| Name | In | Type | Required | About |
|---|
id | path | string | Required | An id that starts ev_. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Errors
Examples
curl https://api.kashupay.com/v1/events/ev_1a2B3c4D5e6F7g8H9i0J1k2L \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const event = await kashu("GET", "/v1/events/ev_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(event.id);
POST /v1/events/{id}/redeliver
Send an event again, now: to one endpoint, or to every enabled endpoint that takes its type.
- Scope
events:write- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Optional. Without one, Kashu makes one and returns it. See Idempotency.
- Answers
- 200 with the Event.
Parameters
| Name | In | Type | Required | About |
|---|
id | path | string | Required | An id that starts ev_. |
Idempotency-Key | header | string | Optional | Optional. When absent, Kashu mints one and returns it. Up to 255 characters. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Request body
| Field | Type | Required | About |
|---|
endpoint | string | Optional | An id that starts we_. |
Errors
| Status | Codes |
|---|
| 400 | invalid_json, parameter_missing, parameter_invalid, parameter_unknown, api_version_invalid, idempotency_key_invalid, idempotency_key_reused |
| 401 | api_key_missing, api_key_invalid, api_key_expired |
| 403 | livemode_unavailable, insufficient_scope, publishable_key_not_allowed |
| 404 | resource_missing |
| 409 | idempotency_key_in_use |
| 429 | rate_limited |
| 500 | api_error |
Examples
curl https://api.kashupay.com/v1/events/ev_1a2B3c4D5e6F7g8H9i0J1k2L/redeliver \
-X POST \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const event = await kashu("POST", "/v1/events/ev_1a2B3c4D5e6F7g8H9i0J1k2L/redeliver");
console.log(event.id);