Event catalog - Ionic Docs

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; subscribe to the ones you handle when you create an endpoint.

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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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

Example payload

{
  "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": "[email protected]",
      "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

Example payload

{
  "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": "[email protected]",
      "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

Example payload

{
  "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": "[email protected]",
      "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

Example payload

{
  "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": "[email protected]",
      "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"
}

​Checkout sessions

​checkout.session.created

​checkout.session.completed

​checkout.session.expired

​Terminal batches

​terminal_batch.closed

​terminal_batch.reconciled

​terminal_batch.incomplete

​terminal_batch.needs_attention

​Charges

​charge.settled

​Payment intents

​payment_intent.created

​payment_intent.requires_action

​payment_intent.succeeded

​payment_intent.payment_failed

​payment_intent.canceled

​Refunds

​refund.created

​refund.succeeded

​refund.failed

​refund.settled

​Invoices

​invoice.paid

​invoice.payment_failed

​invoice.marked_uncollectible

​Subscriptions

​subscription.created

​subscription.updated

​subscription.canceled

​Credit notes

​credit_note.created

​credit_note.voided

​Customers

​customer.created

​customer.updated

​customer.deleted

​customer.restored

Checkout sessions

`checkout.session.created`

`checkout.session.completed`

`checkout.session.expired`

Terminal batches

`terminal_batch.closed`

`terminal_batch.reconciled`

`terminal_batch.incomplete`

`terminal_batch.needs_attention`

Charges

`charge.settled`

Payment intents

`payment_intent.created`

`payment_intent.requires_action`

`payment_intent.succeeded`

`payment_intent.payment_failed`

`payment_intent.canceled`

Refunds

`refund.created`

`refund.succeeded`

`refund.failed`

`refund.settled`

Invoices

`invoice.paid`

`invoice.payment_failed`

`invoice.marked_uncollectible`

Subscriptions

`subscription.created`

`subscription.updated`

`subscription.canceled`

Credit notes

`credit_note.created`

`credit_note.voided`

Customers

`customer.created`

`customer.updated`

`customer.deleted`

`customer.restored`