Fired when a recurring payment fails and the subscription enters a grace window while Commet retries the charge.

Payload

All webhook payloads follow a consistent top-level structure with event-specific data nested within the data object.

subscriptionIdstring

The subscription ID.

customerIdstring

The customer ID. Returns your externalId if you provided one when creating the customer, otherwise returns the Commet publicId.

statusstring

Always "past_due" for this event.

invoiceIdstring

The invoice whose payment failure triggered the status.

invoiceNumberstring

The human-readable invoice number.

{
  "event": "subscription.past_due",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-06-23",
  "data": {
    "subscriptionId": "sub_1a2b3c4d",
    "customerId": "user_123",
    "status": "past_due",
    "invoiceId": "inv_n4o5p6",
    "invoiceNumber": "INV-0043"
  }
}

When this fires

A recurring charge failed on a subscription that has been paid before. Commet sets the status to past_due and enters dunning.

past_due is a permissive grace window — features, usage, and seats keep working. Only purchases and plan changes are blocked. Usage accrues as debt during this window.

Commet retries the charge on day 1, day 3, and day 5 after the failure (3 retries). If a retry succeeds the subscription returns to active. If all 3 retries fail the subscription is canceled.

payment.failed fires alongside this event with the charge failure details (failureCode, failureMessage). Use subscription.past_due to drive your access state and payment.failed to drive recovery messaging.

First-checkout card declines do NOT trigger this event — a subscription that was never paid moves back to pending_payment instead.