Events
Reference for every event Pandabase can send to your webhook endpoints.
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.
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_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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
Fired when a dispute is resolved against the merchant. The deducted funds remain lost and the order stays in CHARGEBACK status.
Payload
Prop
Type
{
"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
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
Prop
Type
{
"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.
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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
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
Prop
Type
{
"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
}
}
}