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,
      "payment_context": null,
      "payment_lifecycle": {
        "attempted_at": "2025-01-01T00:00:00Z",
        "dispatched_at": null,
        "authorized_at": "2025-01-01T00:00:01Z",
        "captured_at": "2025-01-01T00:00:01Z",
        "voided_at": null,
        "finalized_at": "2025-01-01T00:00:01Z"
      }
    }
  },
  "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
        }
      ],
      "livemode": false,
      "metadata": {},
      "number": "TEST-INV-000001",
      "object": "invoice",
      "paid_at": 1735689600,
      "payment_intent": "pi_EXAMPLE",
      "status": "paid",
      "subtotal": 5000,
      "tax": 0,
      "test_clock": null,
      "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
        }
      ],
      "livemode": false,
      "metadata": {},
      "next_payment_attempt_at": 1735689600,
      "number": "TEST-INV-PF-001",
      "object": "invoice",
      "status": "open",
      "subtotal": 5000,
      "tax": 0,
      "test_clock": null,
      "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
        }
      ],
      "livemode": false,
      "metadata": {},
      "number": "TEST-INV-MU-001",
      "object": "invoice",
      "status": "uncollectible",
      "subtotal": 5000,
      "tax": 0,
      "test_clock": null,
      "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",
      "test_clock": null,
      "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",
      "test_clock": null,
      "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",
      "test_clock": null,
      "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,
      "test_clock": 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,
      "test_clock": 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,
      "test_clock": 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,
      "test_clock": null,
      "updated_at": 1735689600
    }
  },
  "id": "evt_EXAMPLE",
  "livemode": false,
  "operations": [
    "update",
    "delete"
  ],
  "type": "customer.restored"
}

Hosted Connect lifecycle

These types are introduced by the Connect lifecycle release (catalog v4). Confirm that the release and your Platform Program are enabled before subscribing.

Types	Meaning	Endpoint scope
`account.created`, `account.updated`	Account creation, safe status/readiness changes, and bound application progress	`connected_accounts` for a Platform; Account’s own `account` stream
`connection.created`, `connection.activated`, `connection.permissions_updated`, `connection.suspended`, `connection.disconnected`	Actual relationship transitions	Owning Platform’s `account` stream
`account_link.created`, `account_link.completed`, `account_link.cancelled`, `account_link.expired`	Hosted visit creation and its single terminal outcome	Owning Platform’s `account` stream

Selecting an existing Account does not emit account.created. A completed visit means merchant actions finished; payments_enabled can remain false while the application is under review. A new Connection emits connection.created; connection.activated describes reactivation after suspension. Subscribe to the Platform-owned and connected-account scopes separately; each endpoint has its own signing secret. Application-derived Account events go only to the originating Platform with its exact active Connection. Pre-consent visit events do not reveal merchant identity. Payloads never include onboarding answers, owner identity, bank information, documents or browser credentials. After verifying the signature, persist the envelope id for deduplication. Advance the snapshot only for a higher data.object.version within the same object ID, mode and version_scope. Scopes are account, connection, account_link, or application:<application_id> on application-derived Account updates. A replacement link starts its own version sequence. Map your customer using the AccountLink ID your server saved; external_reference may repeat.

​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

​Hosted Connect lifecycle

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`

Hosted Connect lifecycle