> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Event catalog
> Every webhook event Ionic sends, with a verified example payload for each.
Ionic sends 29 event types. Each example below uses the same payload shape as a webhook delivery. Every payload is wrapped in the standard [envelope](/webhooks/envelope); subscribe to the ones you handle when you [create an endpoint](/webhooks/endpoints).
Two markers to watch for: **Delayed** events can arrive shortly after the related API response. **Not emitted yet** events are reserved for future use and are not sent in v1.
## Checkout sessions
### `checkout.session.created`
A checkout session is created via `POST /v1/checkout/sessions`.
**`data.object`:** checkout\_session · **operations:** `expire`, `expand`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount_subtotal": 1000,
"amount_total": 1000,
"cancel_url": null,
"client_reference_id": null,
"collect_config": {
"address": "required",
"email": "required",
"name": "required",
"phone": "hidden",
"require_full_billing_address": false,
"require_phone": false,
"require_shipping_address": false,
"wallet_billing_mode": "min"
},
"created_at": 1735689600,
"currency": "USD",
"customer": null,
"customer_email": null,
"expires_at": 1735689600,
"id": "cs_EXAMPLE",
"line_items": [
{
"amount": 1000,
"currency": "USD",
"fulfillment_type": "digital",
"id": "li_EXAMPLE",
"name": "Golden Widget",
"quantity": 1,
"tip_eligible": false
}
],
"livemode": false,
"locale": null,
"merchant_id": "mer_EXAMPLE",
"metadata": {},
"mode": "payment",
"object": "checkout_session",
"payment_intent_id": null,
"payment_status": "unpaid",
"status": "open",
"submit_type": "auto",
"success_url": null,
"ui_mode": "hosted",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"expire",
"expand"
],
"type": "checkout.session.created"
}
```
### `checkout.session.completed`
A session's payment completes and funds are captured. This is the money-moved signal for hosted checkout — fulfill on it.
**`data.object`:** checkout\_session · **operations:** `refund`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount_subtotal": 1000,
"amount_total": 1000,
"cancel_url": null,
"client_reference_id": "order_1001",
"collect_config": {
"address": "required",
"email": "required",
"name": "required",
"phone": "hidden",
"require_full_billing_address": false,
"require_phone": false,
"require_shipping_address": false,
"wallet_billing_mode": "min"
},
"created_at": 1735689600,
"currency": "USD",
"customer": null,
"customer_email": null,
"expires_at": 1735776000,
"id": "cs_000000000000000000001001",
"line_items": [
{
"amount": 1000,
"currency": "USD",
"fulfillment_type": "digital",
"id": "li_000000000000000000001001",
"name": "Golden Widget",
"quantity": 1,
"tip_eligible": false
}
],
"livemode": false,
"locale": null,
"merchant_id": "mer_00000000001001",
"metadata": {
"order_id": "order_1001"
},
"mode": "payment",
"object": "checkout_session",
"payment_intent_id": "pi_000000000000000000001001",
"payment_status": "paid",
"status": "complete",
"submit_type": "auto",
"success_url": null,
"ui_mode": "hosted",
"updated_at": 1735689660
}
},
"id": "evt_000000000000000000001001",
"livemode": false,
"operations": [
"refund"
],
"type": "checkout.session.completed"
}
```
### `checkout.session.expired`
An open session reaches its expiration without completing.
**`data.object`:** checkout\_session · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount_subtotal": 1000,
"amount_total": 1000,
"cancel_url": null,
"client_reference_id": null,
"collect_config": {
"address": "required",
"email": "required",
"name": "required",
"phone": "hidden",
"require_full_billing_address": false,
"require_phone": false,
"require_shipping_address": false,
"wallet_billing_mode": "min"
},
"created_at": 1735689600,
"currency": "USD",
"customer": null,
"customer_email": null,
"expires_at": 1735689600,
"id": "cs_EXAMPLE",
"line_items": [
{
"amount": 1000,
"currency": "USD",
"fulfillment_type": "digital",
"id": "li_EXAMPLE",
"name": "Golden Widget",
"quantity": 1,
"tip_eligible": false
}
],
"livemode": false,
"locale": null,
"merchant_id": "mer_EXAMPLE",
"metadata": {},
"mode": "payment",
"object": "checkout_session",
"payment_intent_id": null,
"payment_status": "unpaid",
"status": "expired",
"submit_type": "auto",
"success_url": null,
"ui_mode": "hosted",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "checkout.session.expired"
}
```
## Terminal batches
### `terminal_batch.closed`
A terminal batch closes.
**`data.object`:** terminal\_batch · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": { "object": {
"closed_at": 1767225600,
"created_at": 1767222000,
"currency": "USD",
"data_as_of": 1767225600,
"id": "tmb_EXAMPLE",
"is_stale": false,
"livemode": false,
"matched_item_count": 0,
"merchant_id": "mer_EXAMPLE",
"object": "terminal_batch",
"opened_at": 1767222000,
"reconciled_at": null,
"reconciliation_status": "pending",
"settlement_profile_id": "stlp_EXAMPLE",
"stale_after": 1767225900,
"status": "closed",
"terminal_ids": ["tmr_EXAMPLE"],
"totals": { "fees": 0, "net": 4000, "refunds": 1000, "sales": 5000, "tax": 0, "tips": 0, "voids": 0 },
"transaction_count": 2,
"unmatched_item_count": 0,
"updated_at": 1767225600
} },
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "terminal_batch.closed"
}
```
### `terminal_batch.reconciled`
Every transaction in a closed terminal batch is matched to Ionic financial records without conflicts.
**`data.object`:** terminal\_batch · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:01:00Z",
"data": { "object": {
"closed_at": 1767225600,
"created_at": 1767222000,
"currency": "USD",
"data_as_of": 1767225600,
"id": "tmb_EXAMPLE",
"is_stale": false,
"livemode": false,
"matched_item_count": 2,
"merchant_id": "mer_EXAMPLE",
"object": "terminal_batch",
"opened_at": 1767222000,
"reconciled_at": 1767225660,
"reconciliation_status": "reconciled",
"settlement_profile_id": "stlp_EXAMPLE",
"stale_after": 1767225900,
"status": "closed",
"terminal_ids": ["tmr_EXAMPLE"],
"totals": { "fees": 0, "net": 4000, "refunds": 1000, "sales": 5000, "tax": 0, "tips": 0, "voids": 0 },
"transaction_count": 2,
"unmatched_item_count": 0,
"updated_at": 1767225660
} },
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "terminal_batch.reconciled"
}
```
### `terminal_batch.incomplete`
A closed terminal batch has one or more transactions that cannot yet be matched to an Ionic financial record.
**`data.object`:** terminal\_batch · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:01:00Z",
"data": { "object": {
"closed_at": 1767225600,
"created_at": 1767222000,
"currency": "USD",
"data_as_of": 1767225600,
"id": "tmb_EXAMPLE",
"is_stale": false,
"livemode": false,
"matched_item_count": 1,
"merchant_id": "mer_EXAMPLE",
"object": "terminal_batch",
"opened_at": 1767222000,
"reconciled_at": null,
"reconciliation_status": "incomplete",
"settlement_profile_id": "stlp_EXAMPLE",
"stale_after": 1767225900,
"status": "closed",
"terminal_ids": ["tmr_EXAMPLE"],
"totals": { "fees": 0, "net": 4000, "refunds": 1000, "sales": 5000, "tax": 0, "tips": 0, "voids": 0 },
"transaction_count": 2,
"unmatched_item_count": 1,
"updated_at": 1767225660
} },
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "terminal_batch.incomplete"
}
```
### `terminal_batch.needs_attention`
A closed terminal batch needs review before its totals can be confirmed.
**`data.object`:** terminal\_batch · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:01:00Z",
"data": { "object": {
"closed_at": 1767225600,
"created_at": 1767222000,
"currency": "USD",
"data_as_of": 1767225600,
"id": "tmb_EXAMPLE",
"is_stale": false,
"livemode": false,
"matched_item_count": 1,
"merchant_id": "mer_EXAMPLE",
"object": "terminal_batch",
"opened_at": 1767222000,
"reconciled_at": null,
"reconciliation_status": "needs_attention",
"settlement_profile_id": "stlp_EXAMPLE",
"stale_after": 1767225900,
"status": "closed",
"terminal_ids": ["tmr_EXAMPLE"],
"totals": { "fees": 0, "net": 4000, "refunds": 1000, "sales": 5000, "tax": 0, "tips": 0, "voids": 0 },
"transaction_count": 2,
"unmatched_item_count": 1,
"updated_at": 1767225660
} },
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "terminal_batch.needs_attention"
}
```
## Charges
### `charge.settled`
A Charge is included in a settled terminal batch.
**`data.object`:** charge · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:01:00Z",
"data": {
"object": {
"amount": 5000,
"amount_refunded": 0,
"authorization_code": "APPROVED",
"created_at": 1735689600,
"currency": "USD",
"decline_code": null,
"decline_type": null,
"failure_message": null,
"id": "ch_EXAMPLE",
"intent_id": "pi_EXAMPLE",
"object": "charge",
"payment_method": "pm_EXAMPLE",
"settled_at": 1767225600,
"settlement_batch_id": "tmb_EXAMPLE",
"status": "succeeded",
"updated_at": 1767225660
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "charge.settled"
}
```
## Payment intents
### `payment_intent.created`
A payment intent is created via `POST /v1/payment_intents`.
**`data.object`:** payment\_intent · **operations:** `confirm`, `cancel`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount": 5000,
"capture_method": "automatic",
"client_secret": null,
"created_at": 1735689600,
"currency": "USD",
"customer": null,
"id": "pi_EXAMPLE",
"latest_charge_id": null,
"livemode": false,
"merchant_id": "mer_EXAMPLE",
"metadata": {},
"object": "payment_intent",
"payment_method": null,
"status": "requires_payment_method",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"confirm",
"cancel"
],
"type": "payment_intent.created"
}
```
### `payment_intent.requires_action`
A payment needs additional buyer authentication, such as 3-D Secure.
Defined in the catalog but not emitted yet — Ionic doesn't run 3DS in v1. It ships now so your handler's switch can be complete.
**`data.object`:** payment\_intent · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-05-01T00:00:00Z",
"data": {
"object": {
"id": "pi_payment00000000000000000",
"object": "payment_intent",
"merchant_id": "mer_merchant000000",
"livemode": false,
"client_secret": null,
"customer": null,
"amount": 2500,
"currency": "USD",
"capture_method": "automatic",
"status": "requires_action",
"payment_method": "pm_method000000000000000000",
"latest_charge_id": "ch_charge000000000000000000",
"metadata": {},
"created_at": 1777593600,
"updated_at": 1777595400
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "payment_intent.requires_action"
}
```
### `payment_intent.succeeded`
A payment intent is captured and succeeds. Folds both automatic-capture success and a manual capture.
**`data.object`:** payment\_intent · **operations:** `refund`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount": 5000,
"capture_method": "automatic",
"client_secret": null,
"created_at": 1735689600,
"currency": "USD",
"customer": null,
"id": "pi_EXAMPLE",
"latest_charge_id": "ch_EXAMPLE",
"livemode": false,
"merchant_id": "mer_EXAMPLE",
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_EXAMPLE",
"status": "succeeded",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"refund"
],
"type": "payment_intent.succeeded"
}
```
### `payment_intent.payment_failed`
A payment attempt is declined or cannot be completed.
**`data.object`:** payment\_intent · **operations:** `retry_with_new_payment_method`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount": 5000,
"capture_method": "automatic",
"client_secret": null,
"created_at": 1735689600,
"currency": "USD",
"customer": null,
"id": "pi_EXAMPLE",
"latest_charge_id": "ch_EXAMPLE",
"livemode": false,
"merchant_id": "mer_EXAMPLE",
"metadata": {},
"object": "payment_intent",
"payment_method": null,
"status": "requires_payment_method",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"retry_with_new_payment_method"
],
"type": "payment_intent.payment_failed"
}
```
### `payment_intent.canceled`
A payment intent is canceled or voided before capture.
**`data.object`:** payment\_intent · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount": 5000,
"capture_method": "automatic",
"client_secret": null,
"created_at": 1735689600,
"currency": "USD",
"customer": null,
"id": "pi_EXAMPLE",
"latest_charge_id": null,
"livemode": false,
"merchant_id": "mer_EXAMPLE",
"metadata": {},
"object": "payment_intent",
"payment_method": null,
"status": "canceled",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "payment_intent.canceled"
}
```
## Refunds
### `refund.created`
A refund is created via `POST /v1/refunds`.
**`data.object`:** refund · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount": 5000,
"charge_id": "ch_EXAMPLE",
"created_at": 1735689600,
"currency": "USD",
"failure_message": null,
"id": "rf_EXAMPLE",
"livemode": false,
"object": "refund",
"payment_intent_id": "pi_EXAMPLE",
"reason": null,
"settled_at": null,
"settlement_batch_id": null,
"status": "pending",
"terminal_id": null,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "refund.created"
}
```
### `refund.succeeded`
A refund succeeds. Its settlement status can update later.
**`data.object`:** refund · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount": 5000,
"charge_id": "ch_EXAMPLE",
"created_at": 1735689600,
"currency": "USD",
"failure_message": null,
"id": "rf_EXAMPLE",
"livemode": false,
"object": "refund",
"payment_intent_id": "pi_EXAMPLE",
"reason": null,
"settled_at": null,
"settlement_batch_id": null,
"status": "succeeded",
"terminal_id": null,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "refund.succeeded"
}
```
### `refund.failed`
A refund attempt fails.
**`data.object`:** refund · **operations:** `retry`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"amount": 5000,
"charge_id": "ch_EXAMPLE",
"created_at": 1735689600,
"currency": "USD",
"failure_message": "already_refunded",
"id": "rf_EXAMPLE",
"livemode": false,
"object": "refund",
"payment_intent_id": "pi_EXAMPLE",
"reason": null,
"settled_at": null,
"settlement_batch_id": null,
"status": "failed",
"terminal_id": null,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"retry"
],
"type": "refund.failed"
}
```
### `refund.settled`
A Refund is included in a settled terminal batch.
**`data.object`:** refund · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:01:00Z",
"data": {
"object": {
"amount": 1000,
"charge_id": "ch_EXAMPLE",
"created_at": 1735689600,
"currency": "USD",
"failure_message": null,
"id": "rf_EXAMPLE",
"livemode": false,
"object": "refund",
"payment_intent_id": "pi_EXAMPLE",
"reason": null,
"settled_at": 1767225600,
"settlement_batch_id": "tmb_EXAMPLE",
"status": "succeeded",
"terminal_id": null,
"updated_at": 1767225660
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "refund.settled"
}
```
## Invoices
Invoice events can arrive shortly after the invoice status changes. Do not require the event to arrive during the API request that caused the change.
### `invoice.paid`
An invoice is paid.
**`data.object`:** invoice · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"allow_save_card": false,
"amount_paid": 5000,
"amount_remaining": 0,
"attempt_count": 0,
"collection_method": "charge_automatically",
"collection_payment_method_id": "pm_EXAMPLE",
"created_at": 1735689600,
"currency": "USD",
"customer": "cus_EXAMPLE",
"finalized_at": 1735689600,
"id": "inv_EXAMPLE",
"lines": [
{
"amount": 5000,
"currency": "USD",
"description": "Golden Invoice Item",
"id": "il_EXAMPLE",
"quantity": 1,
"unit_amount": 5000
}
],
"metadata": {},
"number": "TEST-INV-000001",
"object": "invoice",
"paid_at": 1735689600,
"payment_intent": "pi_EXAMPLE",
"status": "paid",
"subtotal": 5000,
"tax": 0,
"total": 5000,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "invoice.paid"
}
```
### `invoice.payment_failed`
A collection attempt is declined and a retry is scheduled. (There is no separate `invoice.payment_attempted` event — a failed attempt that schedules a retry is the failure signal.)
**`data.object`:** invoice · **operations:** `update_payment_method`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"allow_save_card": false,
"amount_paid": 0,
"amount_remaining": 5000,
"attempt_count": 1,
"collection_method": "send_invoice",
"created_at": 1735689600,
"currency": "USD",
"customer": "cus_EXAMPLE",
"finalized_at": 1735689600,
"id": "inv_EXAMPLE",
"lines": [
{
"amount": 5000,
"currency": "USD",
"description": "Plan",
"id": "il_EXAMPLE",
"quantity": 1,
"unit_amount": 5000
}
],
"metadata": {},
"next_payment_attempt_at": 1735689600,
"number": "TEST-INV-PF-001",
"object": "invoice",
"status": "open",
"subtotal": 5000,
"tax": 0,
"total": 5000,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"update_payment_method"
],
"type": "invoice.payment_failed"
}
```
### `invoice.marked_uncollectible`
Dunning is exhausted and the invoice is marked uncollectible — the final, no-retry failure.
**`data.object`:** invoice · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"allow_save_card": false,
"amount_paid": 0,
"amount_remaining": 5000,
"attempt_count": 0,
"collection_method": "send_invoice",
"created_at": 1735689600,
"currency": "USD",
"customer": "cus_EXAMPLE",
"finalized_at": 1735689600,
"id": "inv_EXAMPLE",
"lines": [
{
"amount": 5000,
"currency": "USD",
"description": "Plan",
"id": "il_EXAMPLE",
"quantity": 1,
"unit_amount": 5000
}
],
"metadata": {},
"number": "TEST-INV-MU-001",
"object": "invoice",
"status": "uncollectible",
"subtotal": 5000,
"tax": 0,
"total": 5000,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "invoice.marked_uncollectible"
}
```
## Subscriptions
### `subscription.created`
A subscription is first created, via the API or a subscription-mode checkout. Fires once, before any update.
**`data.object`:** subscription · **operations:** `cancel`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"billing_cycle_anchor": 1735689600,
"cancel_at_period_end": false,
"collection_method": "send_invoice",
"created_at": 1735689600,
"current_period_end": 1735689600,
"current_period_start": 1735689600,
"customer": "cus_EXAMPLE",
"id": "sub_EXAMPLE",
"items": [
{
"id": "si_EXAMPLE",
"metadata": {},
"price": "price_EXAMPLE",
"quantity": 1
}
],
"livemode": false,
"metadata": {},
"object": "subscription",
"status": "incomplete",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"cancel"
],
"type": "subscription.created"
}
```
### `subscription.updated`
A subscription's status or configuration changes. This is the catch-all signal — activation, past-due, resume, item or payment-method changes, and a scheduled cancel-at-period-end all fold into it. Read `data.object` for the new state.
**`data.object`:** subscription · **operations:** `cancel`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"billing_cycle_anchor": 1735689600,
"cancel_at_period_end": false,
"collection_method": "send_invoice",
"created_at": 1735689600,
"current_period_end": 1735689600,
"current_period_start": 1735689600,
"customer": "cus_EXAMPLE",
"id": "sub_EXAMPLE",
"items": [
{
"id": "si_EXAMPLE",
"metadata": {},
"price": "price_EXAMPLE",
"quantity": 1
}
],
"livemode": false,
"metadata": {
"plan_tier": "pro"
},
"object": "subscription",
"status": "incomplete",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"cancel"
],
"type": "subscription.updated"
}
```
### `subscription.canceled`
A subscription is canceled immediately — service stops now. A scheduled cancel-at-period-end is a `subscription.updated`, not this, so you don't revoke access early.
**`data.object`:** subscription · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"billing_cycle_anchor": 1735689600,
"cancel_at_period_end": false,
"canceled_at": 1735689600,
"collection_method": "send_invoice",
"created_at": 1735689600,
"current_period_end": 1735689600,
"current_period_start": 1735689600,
"customer": "cus_EXAMPLE",
"ended_at": 1735689600,
"id": "sub_EXAMPLE",
"items": [
{
"id": "si_EXAMPLE",
"metadata": {},
"price": "price_EXAMPLE",
"quantity": 1
}
],
"livemode": false,
"metadata": {
"plan_tier": "pro"
},
"object": "subscription",
"status": "canceled",
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "subscription.canceled"
}
```
## Credit notes
### `credit_note.created`
A credit note is issued against an invoice.
**`data.object`:** credit\_note · **operations:** `void`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-05-01T00:00:00Z",
"data": {
"object": {
"id": "cn_creditnote00000000000000",
"object": "credit_note",
"number": "CN-GOLDEN-0001",
"invoice": "inv_invoice00000000000000000",
"customer": "cus_customer000000",
"currency": "USD",
"status": "issued",
"reason": "product_unsatisfactory",
"type": "post_payment",
"subtotal": 2500,
"tax": 0,
"total": 2500,
"amount_refunded": 0,
"out_of_band_amount": 2500,
"refund": null,
"lines": [
{
"id": "cnl_line00000000000000000000",
"object": "credit_note_line_item",
"type": "custom_line_item",
"invoice_line_item": null,
"description": "Credit — Pro plan",
"quantity": null,
"unit_amount": null,
"amount": 2500,
"tax": 0,
"livemode": false
}
],
"memo": null,
"metadata": {},
"livemode": false,
"created": 1777593600,
"effective_at": 1777593600,
"voided_at": null
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"void"
],
"type": "credit_note.created"
}
```
### `credit_note.voided`
A credit note is voided.
**`data.object`:** credit\_note · **operations:** none
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-05-01T00:00:00Z",
"data": {
"object": {
"id": "cn_creditnote00000000000000",
"object": "credit_note",
"number": "CN-GOLDEN-0001",
"invoice": "inv_invoice00000000000000000",
"customer": "cus_customer000000",
"currency": "USD",
"status": "void",
"reason": "product_unsatisfactory",
"type": "post_payment",
"subtotal": 2500,
"tax": 0,
"total": 2500,
"amount_refunded": 0,
"out_of_band_amount": 2500,
"refund": null,
"lines": [
{
"id": "cnl_line00000000000000000000",
"object": "credit_note_line_item",
"type": "custom_line_item",
"invoice_line_item": null,
"description": "Credit — Pro plan",
"quantity": null,
"unit_amount": null,
"amount": 2500,
"tax": 0,
"livemode": false
}
],
"memo": null,
"metadata": {},
"livemode": false,
"created": 1777593600,
"effective_at": 1777593600,
"voided_at": 1777595400
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [],
"type": "credit_note.voided"
}
```
## Customers
### `customer.created`
A customer is created via `POST /v1/customers`.
**`data.object`:** customer · **operations:** `update`, `delete`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"billing_address": null,
"created_at": 1735689600,
"creation_source": "api",
"deleted": false,
"email": "ada.lovelace@example.com",
"first_name": "Ada",
"id": "cus_EXAMPLE",
"last_name": "Lovelace",
"merchant_id": "mer_EXAMPLE",
"livemode": false,
"metadata": {},
"object": "customer",
"payment_settings": {},
"phone": "",
"shipping": null,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"update",
"delete"
],
"type": "customer.created"
}
```
### `customer.updated`
A customer's details change.
**`data.object`:** customer · **operations:** `update`, `delete`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"billing_address": null,
"created_at": 1735689600,
"creation_source": "api",
"deleted": false,
"email": "ada.lovelace@example.com",
"first_name": "Ada",
"id": "cus_EXAMPLE",
"last_name": "Lovelace",
"merchant_id": "mer_EXAMPLE",
"livemode": false,
"metadata": {},
"object": "customer",
"payment_settings": {},
"phone": "+15555550123",
"shipping": null,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"update",
"delete"
],
"type": "customer.updated"
}
```
### `customer.deleted`
A customer is soft-deleted via `DELETE /v1/customers/{id}`.
**`data.object`:** customer · **operations:** `restore`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"billing_address": null,
"created_at": 1735689600,
"creation_source": "api",
"deleted": true,
"email": "ada.lovelace@example.com",
"first_name": "Ada",
"id": "cus_EXAMPLE",
"last_name": "Lovelace",
"merchant_id": "mer_EXAMPLE",
"livemode": false,
"metadata": {},
"object": "customer",
"payment_settings": {},
"phone": "+15555550123",
"shipping": null,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"restore"
],
"type": "customer.deleted"
}
```
### `customer.restored`
A soft-deleted customer is restored via `POST /v1/customers/{id}/restore`.
**`data.object`:** customer · **operations:** `update`, `delete`
```json theme={null}
{
"api_version": "2026-05-01",
"created": "2026-01-01T00:00:00Z",
"data": {
"object": {
"billing_address": null,
"created_at": 1735689600,
"creation_source": "api",
"deleted": false,
"email": "ada.lovelace@example.com",
"first_name": "Ada",
"id": "cus_EXAMPLE",
"last_name": "Lovelace",
"merchant_id": "mer_EXAMPLE",
"livemode": false,
"metadata": {},
"object": "customer",
"payment_settings": {},
"phone": "+15555550123",
"shipping": null,
"updated_at": 1735689600
}
},
"id": "evt_EXAMPLE",
"livemode": false,
"operations": [
"update",
"delete"
],
"type": "customer.restored"
}
```