This page lists every event Pandabase sends and what each one means. For delivery semantics, signature verification, and retry behavior, see the Webhooks overview.

All event types

Event	Description
`PAYMENT_PENDING`	A customer initiated payment at checkout and the order is awaiting confirmation.
`PAYMENT_COMPLETED`	A payment was successfully collected — the primary event for fulfilling orders.
`PAYMENT_FAILED`	A payment failed, was canceled, or expired without completing.
`PAYMENT_REFUNDED`	A charge was refunded and the order moved to refunded status.
`PAYMENT_DISPUTED`	A customer opened a chargeback dispute on a payment.
`PAYMENT_DISPUTE_WON`	A dispute was resolved in the merchant’s favor and funds were restored.
`PAYMENT_DISPUTE_LOST`	A dispute was resolved against the merchant and funds remain lost.
`PAYMENT_DISPUTE_PREVENTED`	A chargeback was prevented before becoming a formal dispute.
`SUBSCRIPTION_CREATED`	A new subscription was activated via checkout or a free trial.
`SUBSCRIPTION_RENEWED`	A recurring subscription payment was successfully collected.
`SUBSCRIPTION_PAST_DUE`	A renewal payment failed or requires additional authentication.
`SUBSCRIPTION_CANCELLED`	A subscription was cancelled by the merchant, customer, or failed retries.
`SUBSCRIPTION_PAUSED`	A merchant paused a subscription, halting further charges.
`SUBSCRIPTION_RESUMED`	A merchant resumed a previously paused subscription.
`SUBSCRIPTION_UPDATED`	A subscription’s plan, quantity, or payment method changed.
`SUBSCRIPTION_TRIAL_ENDING`	A trial is ending soon and billing is about to begin.
`SUBSCRIPTION_RENEWING`	A subscription is about to renew (sent a few days before the charge).

Payload shape

Every delivery is a JSON POST with the event type, a unique event ID, a timestamp, and a data object.

webhook.d.ts

type WebhookEvent =  | "PAYMENT_PENDING"  | "PAYMENT_COMPLETED"  | "PAYMENT_FAILED"  | "PAYMENT_REFUNDED"  | "PAYMENT_DISPUTED"  | "PAYMENT_DISPUTE_WON"  | "PAYMENT_DISPUTE_LOST"  | "PAYMENT_DISPUTE_PREVENTED"  | "SUBSCRIPTION_CREATED"  | "SUBSCRIPTION_RENEWED"  | "SUBSCRIPTION_PAST_DUE"  | "SUBSCRIPTION_CANCELLED"  | "SUBSCRIPTION_PAUSED"  | "SUBSCRIPTION_RESUMED"  | "SUBSCRIPTION_UPDATED"  | "SUBSCRIPTION_TRIAL_ENDING"  | "SUBSCRIPTION_RENEWING";

All monetary values are in cents (integers, no floats).

Payment events

POST PAYMENT_PENDING

Delivered to your webhook endpoint as a POST request when this event occurs.

A customer initiated payment at checkout and the order is awaiting confirmation.

Fired when a customer initiates payment at checkout. The order has been created and a payment intent is awaiting confirmation.

At this stage, geo data (city, region, country) may be null — it is enriched asynchronously after checkout. Subsequent events will include full geo data.

Payload

event string required

The event type — always PAYMENT_PENDING.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order associated with this event. See the payload shape.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request. Often null at this stage — enriched asynchronously.

Payload

{  "event": "PAYMENT_PENDING",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-03-07T12:00:00.000Z",  "data": {    "order": {      "id": "ord_cm5x7k2a000001j0g8h3f9d2e",      "orderNumber": "cs_cm5x7k2a000001j0g8h3f9d2e",      "status": "PENDING",      "amount": 5000,      "currency": "USD",      "customFields": { "discord": "johndoe#1234" },      "metadata": { "campaign": "spring_sale" },      "items": [        {          "productId": "prd_cm5x7k2a000001j0g8h3f9d2e",          "variantId": null,          "name": "Pro Plan",          "quantity": 1,          "amount": 5000        }      ]    },    "customer": {},    "geo": null  }}

POST PAYMENT_COMPLETED

Delivered to your webhook endpoint as a POST request when this event occurs.

A payment was successfully collected — the primary event for fulfilling orders.

Fired when a payment is successfully collected. This is the primary event to listen for when fulfilling orders.

The order status will be PROCESSING (if fulfillment is in progress) or COMPLETED (if already fulfilled). The items array contains all purchased products, customFields includes any data the customer submitted at checkout, and metadata contains any developer-defined key-value pairs set when creating the checkout session.

Payload

event string required

The event type — always PAYMENT_COMPLETED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The completed order, with status PROCESSING or COMPLETED.

data.customer object | null

The customer who placed the order.

data.geo object | null

Geo data for the request, or null if not available.

Payload

{  "event": "PAYMENT_COMPLETED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-03-07T12:00:00.000Z",  "data": {    "order": {      "id": "ord_cm5x7k2a000001j0g8h3f9d2e",      "orderNumber": "cs_cm5x7k2a000001j0g8h3f9d2e",      "status": "COMPLETED",      "amount": 5000,      "currency": "USD",      "customFields": { "discord": "johndoe#1234" },      "metadata": { "campaign": "spring_sale", "ref": "partner_abc" },      "items": [        {          "productId": "prd_cm5x7k2a000001j0g8h3f9d2e",          "variantId": null,          "name": "Pro Plan",          "quantity": 1,          "amount": 5000        }      ]    },    "customer": {},    "geo": {      "ip": "1.2.3.4",      "country": "US",      "city": "Miami",      "region": "FL"    }  }}

POST PAYMENT_FAILED

Delivered to your webhook endpoint as a POST request when this event occurs.

A payment failed, was canceled, or expired without completing.

Fired when a payment fails, is canceled by the customer, or expires without being completed. The order is moved to CANCELLED status. If a coupon was applied, its usage count is automatically restored.

Payload

event string required

The event type — always PAYMENT_FAILED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order, now in CANCELLED status.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

Payload

{  "event": "PAYMENT_FAILED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-03-07T12:05:00.000Z",  "data": {    "order": {      "id": "ord_cm5x7k2a000001j0g8h3f9d2e",      "orderNumber": "cs_cm5x7k2a000001j0g8h3f9d2e",      "status": "CANCELLED",      "amount": 5000,      "currency": "USD",      "customFields": null,      "metadata": null,      "items": [        {          "productId": "prd_cm5x7k2a000001j0g8h3f9d2e",          "variantId": null,          "name": "Pro Plan",          "quantity": 1,          "amount": 5000        }      ]    },    "customer": {},    "geo": null  }}

POST PAYMENT_REFUNDED

Delivered to your webhook endpoint as a POST request when this event occurs.

A charge was refunded and the order moved to refunded status.

Fired when a charge is refunded, whether initiated through the Pandabase dashboard or detected from an external refund. The order status is set to REFUNDED.

Payload

event string required

The event type — always PAYMENT_REFUNDED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order, now in REFUNDED status.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

Payload

{  "event": "PAYMENT_REFUNDED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-03-09T09:30:00.000Z",  "data": {    "order": {      "id": "ord_cm5x7k2a000001j0g8h3f9d2e",      "orderNumber": "cs_cm5x7k2a000001j0g8h3f9d2e",      "status": "REFUNDED",      "amount": 5000,      "currency": "USD",      "customFields": null,      "metadata": null,      "items": [        {          "productId": "prd_cm5x7k2a000001j0g8h3f9d2e",          "variantId": null,          "name": "Pro Plan",          "quantity": 1,          "amount": 5000        }      ]    },    "customer": {},    "geo": null  }}

POST PAYMENT_DISPUTED

Delivered to your webhook endpoint as a POST request when this event occurs.

A customer opened a chargeback dispute on a payment.

Fired when a customer opens a chargeback dispute on a payment. The order moves to CHARGEBACK status and the disputed amount plus a $20.00 dispute fee is deducted from the store’s available balance.

Payload

event string required

The event type — always PAYMENT_DISPUTED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order, now in CHARGEBACK status.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

Payload

{  "event": "PAYMENT_DISPUTED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-03-12T14:00:00.000Z",  "data": {    "order": {      "id": "ord_cm5x7k2a000001j0g8h3f9d2e",      "orderNumber": "cs_cm5x7k2a000001j0g8h3f9d2e",      "status": "CHARGEBACK",      "amount": 5000,      "currency": "USD",      "customFields": null,      "metadata": null,      "items": [        {          "productId": "prd_cm5x7k2a000001j0g8h3f9d2e",          "variantId": null,          "name": "Pro Plan",          "quantity": 1,          "amount": 5000        }      ]    },    "customer": {},    "geo": null  }}

POST PAYMENT_DISPUTE_WON

Delivered to your webhook endpoint as a POST request when this event occurs.

A dispute was resolved in the merchant's favor and funds were restored.

Fired when a dispute is resolved in the merchant’s favor. The disputed amount and fee are restored to the store’s available balance and the order returns to COMPLETED status.

Payload

event string required

The event type — always PAYMENT_DISPUTE_WON.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order, returned to COMPLETED status.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

Payload

{  "event": "PAYMENT_DISPUTE_WON",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-03-20T10:00:00.000Z",  "data": {    "order": {      "id": "ord_cm5x7k2a000001j0g8h3f9d2e",      "orderNumber": "cs_cm5x7k2a000001j0g8h3f9d2e",      "status": "COMPLETED",      "amount": 5000,      "currency": "USD",      "customFields": null,      "metadata": null,      "items": [        {          "productId": "prd_cm5x7k2a000001j0g8h3f9d2e",          "variantId": null,          "name": "Pro Plan",          "quantity": 1,          "amount": 5000        }      ]    },    "customer": {},    "geo": null  }}

POST PAYMENT_DISPUTE_LOST

Delivered to your webhook endpoint as a POST request when this event occurs.

A dispute was resolved against the merchant and funds remain lost.

Fired when a dispute is resolved against the merchant. The deducted funds remain lost and the order stays in CHARGEBACK status.

Payload

event string required

The event type — always PAYMENT_DISPUTE_LOST.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order, which remains in CHARGEBACK status.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

Payload

{  "event": "PAYMENT_DISPUTE_LOST",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-03-20T10:00:00.000Z",  "data": {    "order": {      "id": "ord_cm5x7k2a000001j0g8h3f9d2e",      "orderNumber": "cs_cm5x7k2a000001j0g8h3f9d2e",      "status": "CHARGEBACK",      "amount": 5000,      "currency": "USD",      "customFields": null,      "metadata": null,      "items": [        {          "productId": "prd_cm5x7k2a000001j0g8h3f9d2e",          "variantId": null,          "name": "Pro Plan",          "quantity": 1,          "amount": 5000        }      ]    },    "customer": {},    "geo": null  }}

POST PAYMENT_DISPUTE_PREVENTED

Delivered to your webhook endpoint as a POST request when this event occurs.

A chargeback was prevented before becoming a formal dispute.

Fired when Verifi (Visa RDR) or Ethoca prevents a chargeback before it becomes a formal dispute. This is terminal — no PAYMENT_DISPUTE_WON or PAYMENT_DISPUTE_LOST will follow.

The order moves to CHARGEBACK status. The disputed amount plus a $30.00 prevention fee is deducted from the store’s available balance. Prevented disputes do not count toward your dispute rate.

Payload

event string required

The event type — always PAYMENT_DISPUTE_PREVENTED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order, now in CHARGEBACK status.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

Payload

{  "event": "PAYMENT_DISPUTE_PREVENTED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-03-15T08:00:00.000Z",  "data": {    "order": {      "id": "ord_cm5x7k2a000001j0g8h3f9d2e",      "orderNumber": "cs_cm5x7k2a000001j0g8h3f9d2e",      "status": "CHARGEBACK",      "amount": 5000,      "currency": "USD",      "customFields": null,      "metadata": null,      "items": [        {          "productId": "prd_cm5x7k2a000001j0g8h3f9d2e",          "variantId": null,          "name": "Pro Plan",          "quantity": 1,          "amount": 5000        }      ]    },    "customer": {},    "geo": null  }}

Subscription events

Subscription events include the same order, customer, and geo fields as payment events, plus a subscription object with the current subscription state. They are fired alongside (not instead of) payment events — for example, a successful renewal triggers both PAYMENT_COMPLETED and SUBSCRIPTION_RENEWED.

Subscription type

interface WebhookSubscription {  id: string; // sub_ prefixed  status: "TRIALING" | "ACTIVE" | "PAST_DUE" | "PAUSED" | "CANCELLED";  billingInterval: "WEEKLY" | "MONTHLY" | "YEARLY";  amount: number; // cents  currency: string;  currentPeriodStart: string; // ISO 8601  currentPeriodEnd: string;  nextChargeAt: string | null; // null when cancelled/paused  trialEnd: string | null;  cancelledAt: string | null;}

The subscription field is only present on SUBSCRIPTION_* events. Payment events (PAYMENT_COMPLETED, etc.) do not include it.

POST SUBSCRIPTION_CREATED

Delivered to your webhook endpoint as a POST request when this event occurs.

A new subscription was activated via checkout or a free trial.

Fired when a new subscription is activated:

A customer completes checkout for a subscription product (first payment collected), or
A customer starts a free trial (card saved, no charge).

The order in the payload is the initial order that created the subscription. For trial subscriptions, the initial order has an amount of $0.00 — the first charge happens when the trial ends.

Payload

event string required

The event type — always SUBSCRIPTION_CREATED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The initial order that created the subscription.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The newly created subscription. For trials, status is TRIALING and trialEnd is set.

Payload

{  "event": "SUBSCRIPTION_CREATED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-04-18T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "ACTIVE",      "billingInterval": "MONTHLY",      "amount": 1999,      "currency": "USD",      "currentPeriodStart": "2026-04-18T00:00:00.000Z",      "currentPeriodEnd": "2026-05-18T00:00:00.000Z",      "nextChargeAt": "2026-05-18T00:00:00.000Z",      "trialEnd": null,      "cancelledAt": null    }  }}

POST SUBSCRIPTION_RENEWED

Delivered to your webhook endpoint as a POST request when this event occurs.

A recurring subscription payment was successfully collected.

Fired when a recurring payment is successfully collected. Sent on every billing cycle — weekly, monthly, or yearly depending on the subscription’s billing interval. Use this event to extend access, deliver license keys, or update entitlements.

Payload

event string required

The event type — always SUBSCRIPTION_RENEWED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order generated for this billing cycle.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The subscription with its updated billing period.

Payload

{  "event": "SUBSCRIPTION_RENEWED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-04-18T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "ACTIVE",      "billingInterval": "MONTHLY",      "amount": 1999,      "currency": "USD",      "currentPeriodStart": "2026-04-18T00:00:00.000Z",      "currentPeriodEnd": "2026-05-18T00:00:00.000Z",      "nextChargeAt": "2026-05-18T00:00:00.000Z",      "trialEnd": null,      "cancelledAt": null    }  }}

POST SUBSCRIPTION_PAST_DUE

Delivered to your webhook endpoint as a POST request when this event occurs.

A renewal payment failed or requires additional authentication.

Fired when a renewal payment fails or requires additional authentication (3D Secure). The subscription moves to PAST_DUE status. Causes include:

The customer’s card was declined
The card requires 3DS verification (customer is emailed an authentication link)
The payment method has expired

Failed payments are automatically retried up to 3 times over 3 days (24h, 48h, 72h). If all retries fail, the subscription is cancelled and a SUBSCRIPTION_CANCELLED event is fired.

Do not revoke access on SUBSCRIPTION_PAST_DUE — the customer may still authenticate or the retry may succeed. Wait for SUBSCRIPTION_CANCELLED before revoking.

Payload

event string required

The event type — always SUBSCRIPTION_PAST_DUE.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order for the failed renewal attempt.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The subscription, now in PAST_DUE status.

Payload

{  "event": "SUBSCRIPTION_PAST_DUE",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-05-18T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "PAST_DUE",      "billingInterval": "MONTHLY",      "amount": 1999,      "currency": "USD",      "currentPeriodStart": "2026-04-18T00:00:00.000Z",      "currentPeriodEnd": "2026-05-18T00:00:00.000Z",      "nextChargeAt": "2026-05-19T00:00:00.000Z",      "trialEnd": null,      "cancelledAt": null    }  }}

POST SUBSCRIPTION_CANCELLED

Delivered to your webhook endpoint as a POST request when this event occurs.

A subscription was cancelled by the merchant, customer, or failed retries.

Fired when a subscription is cancelled. Causes include:

The merchant cancels the subscription (immediately or at period end)
The customer cancels from the customer portal (always at period end)
All automatic payment retries are exhausted

If cancelled at period end, the customer retains access until the current billing period ends. Check the order’s metadata or the subscription API for the endsAt date.

Payload

event string required

The event type — always SUBSCRIPTION_CANCELLED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order associated with the subscription.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The subscription, now in CANCELLED status with cancelledAt set.

Payload

{  "event": "SUBSCRIPTION_CANCELLED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-05-21T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "CANCELLED",      "billingInterval": "MONTHLY",      "amount": 1999,      "currency": "USD",      "currentPeriodStart": "2026-04-18T00:00:00.000Z",      "currentPeriodEnd": "2026-05-18T00:00:00.000Z",      "nextChargeAt": null,      "trialEnd": null,      "cancelledAt": "2026-05-21T00:00:00.000Z"    }  }}

POST SUBSCRIPTION_PAUSED

Delivered to your webhook endpoint as a POST request when this event occurs.

A merchant paused a subscription, halting further charges.

Fired when a merchant pauses a subscription. No further charges are made until the subscription is resumed. The customer retains access during the pause.

Payload

event string required

The event type — always SUBSCRIPTION_PAUSED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order associated with the subscription.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The subscription, now in PAUSED status with nextChargeAt set to null.

Payload

{  "event": "SUBSCRIPTION_PAUSED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-05-01T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "PAUSED",      "billingInterval": "MONTHLY",      "amount": 1999,      "currency": "USD",      "currentPeriodStart": "2026-04-18T00:00:00.000Z",      "currentPeriodEnd": "2026-05-18T00:00:00.000Z",      "nextChargeAt": null,      "trialEnd": null,      "cancelledAt": null    }  }}

POST SUBSCRIPTION_RESUMED

Delivered to your webhook endpoint as a POST request when this event occurs.

A merchant resumed a previously paused subscription.

Fired when a merchant resumes a previously paused subscription. Billing resumes at the end of the current period (or immediately if the period has already ended).

Payload

event string required

The event type — always SUBSCRIPTION_RESUMED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order associated with the subscription.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The subscription, returned to ACTIVE status with nextChargeAt set again.

Payload

{  "event": "SUBSCRIPTION_RESUMED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-05-10T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "ACTIVE",      "billingInterval": "MONTHLY",      "amount": 1999,      "currency": "USD",      "currentPeriodStart": "2026-04-18T00:00:00.000Z",      "currentPeriodEnd": "2026-05-18T00:00:00.000Z",      "nextChargeAt": "2026-05-18T00:00:00.000Z",      "trialEnd": null,      "cancelledAt": null    }  }}

POST SUBSCRIPTION_UPDATED

Delivered to your webhook endpoint as a POST request when this event occurs.

A subscription's plan, quantity, or payment method changed.

Fired when a subscription is changed — its product, variant, billing interval, or quantity is updated, or the card it bills is changed. For an immediate upgrade that prorates, this fires alongside PAYMENT_COMPLETED for the prorated charge; an end-of-period change takes effect at the next renewal. The subscription object reflects the new plan.

Payload

event string required

The event type — always SUBSCRIPTION_UPDATED.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order associated with the subscription.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The subscription with its new plan applied.

Payload

{  "event": "SUBSCRIPTION_UPDATED",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-06-07T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "ACTIVE",      "billingInterval": "YEARLY",      "amount": 19999,      "currency": "USD",      "currentPeriodStart": "2026-06-07T00:00:00.000Z",      "currentPeriodEnd": "2027-06-07T00:00:00.000Z",      "nextChargeAt": "2027-06-07T00:00:00.000Z",      "trialEnd": null,      "cancelledAt": null    }  }}

POST SUBSCRIPTION_TRIAL_ENDING

Delivered to your webhook endpoint as a POST request when this event occurs.

A trial is ending soon and billing is about to begin.

Fired a few days before a free trial ends, so you can remind the customer that billing is about to start. The first charge is attempted when the trial ends (trialEnd). This is an advisory event and is not tied to a payment.

Payload

event string required

The event type — always SUBSCRIPTION_TRIAL_ENDING.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order associated with the subscription.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The trialing subscription, with trialEnd set to when billing begins.

Payload

{  "event": "SUBSCRIPTION_TRIAL_ENDING",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-06-07T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "TRIALING",      "billingInterval": "MONTHLY",      "amount": 1999,      "currency": "USD",      "currentPeriodStart": "2026-06-07T00:00:00.000Z",      "currentPeriodEnd": "2026-06-14T00:00:00.000Z",      "nextChargeAt": "2026-06-14T00:00:00.000Z",      "trialEnd": "2026-06-14T00:00:00.000Z",      "cancelledAt": null    }  }}

POST SUBSCRIPTION_RENEWING

Delivered to your webhook endpoint as a POST request when this event occurs.

A subscription is about to renew.

Fired a few days before a subscription’s next renewal, so you can notify the customer ahead of the charge. For the exact amount — including metered usage and tax — call the upcoming invoice endpoint. This is an advisory event and is not tied to a payment.

Payload

event string required

The event type — always SUBSCRIPTION_RENEWING.

id string required

Unique identifier for the event, prefixed with evt_.

timestamp string required

ISO 8601 timestamp of when the event occurred.

data.order object required

The order associated with the subscription.

data.customer object | null

The customer, or null if not available.

data.geo object | null

Geo data for the request, or null if not available.

data.subscription object required

The subscription due to renew, with nextChargeAt set to the upcoming charge date.

Payload

{  "event": "SUBSCRIPTION_RENEWING",  "id": "evt_cm5x7k2a000001j0g8h3f9d2e",  "timestamp": "2026-06-07T00:00:00.000Z",  "data": {    "order": {},    "customer": {},    "geo": null,    "subscription": {      "id": "sub_cm5x7k2a000001j0g8h3f9d2e",      "status": "ACTIVE",      "billingInterval": "MONTHLY",      "amount": 1999,      "currency": "USD",      "currentPeriodStart": "2026-05-10T00:00:00.000Z",      "currentPeriodEnd": "2026-06-10T00:00:00.000Z",      "nextChargeAt": "2026-06-10T00:00:00.000Z",      "trialEnd": null,      "cancelledAt": null    }  }}