# Events (/developers/webhooks/events)
This page lists every event Pandabase sends and what each one means. For delivery semantics, signature verification, and retry behavior, see the [Webhooks overview](/developers/webhooks/overview).
## All event types [#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 [#payload-shape]
Every delivery is a JSON `POST` with the event type, a unique event ID, a timestamp, and a `data` object.
```typescript title="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 [#payment-events]
***
### PAYMENT\_PENDING [#payment_pending]
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 [#payload]
```json title="Example event"
{
"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
}
}
```
***
### PAYMENT\_COMPLETED [#payment_completed]
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 [#payload-1]
```json title="Example event"
{
"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"
}
}
}
```
***
### PAYMENT\_FAILED [#payment_failed]
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 [#payload-2]
```json title="Example event"
{
"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
}
}
```
***
### PAYMENT\_REFUNDED [#payment_refunded]
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 [#payload-3]
```json title="Example event"
{
"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
}
}
```
***
### PAYMENT\_DISPUTED [#payment_disputed]
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 [#payload-4]
```json title="Example event"
{
"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
}
}
```
***
### PAYMENT\_DISPUTE\_WON [#payment_dispute_won]
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 [#payload-5]
```json title="Example event"
{
"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
}
}
```
***
### PAYMENT\_DISPUTE\_LOST [#payment_dispute_lost]
Fired when a dispute is resolved against the merchant. The deducted funds remain lost and the order stays in `CHARGEBACK` status.
#### Payload [#payload-6]
```json title="Example event"
{
"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
}
}
```
***
### PAYMENT\_DISPUTE\_PREVENTED [#payment_dispute_prevented]
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 [#payload-7]
```json title="Example event"
{
"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]
***
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`.
```typescript title="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.
### SUBSCRIPTION\_CREATED [#subscription_created]
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 [#payload-8]
```json title="Example event"
{
"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
}
}
}
```
***
### SUBSCRIPTION\_RENEWED [#subscription_renewed]
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 [#payload-9]
```json title="Example event"
{
"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
}
}
}
```
***
### SUBSCRIPTION\_PAST\_DUE [#subscription_past_due]
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 [#payload-10]
```json title="Example event"
{
"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
}
}
}
```
***
### SUBSCRIPTION\_CANCELLED [#subscription_cancelled]
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 [#payload-11]
```json title="Example event"
{
"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"
}
}
}
```
***
### SUBSCRIPTION\_PAUSED [#subscription_paused]
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 [#payload-12]
```json title="Example event"
{
"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
}
}
}
```
***
### SUBSCRIPTION\_RESUMED [#subscription_resumed]
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 [#payload-13]
```json title="Example event"
{
"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
}
}
}
```
***
### SUBSCRIPTION\_UPDATED [#subscription_updated]
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 [#payload-14]
```json title="Example event"
{
"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
}
}
}
```
***
### SUBSCRIPTION\_TRIAL\_ENDING [#subscription_trial_ending]
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 [#payload-15]
```json title="Example event"
{
"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
}
}
}
```
***
### SUBSCRIPTION\_RENEWING [#subscription_renewing]
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](/developers/api/store-api-reference/subscriptions) endpoint. This is an advisory event and is not tied to a payment.
#### Payload [#payload-16]
```json title="Example event"
{
"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
}
}
}
```