> ## Documentation Index
> Fetch the complete documentation index at: https://commet.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# payment.failed

> Fired when a subscription charge fails, including resume charges and recovery attempts

## paymentContext

The original reason for a charge and how this attempt was initiated. Recovery never replaces the original reason. Context can be null when it was not captured, including retries of historical invoices.

> [accordion] Fields and payment reasons
>
> ### `reason`
>
> `string`
>
> The original reason, preserved across payment attempts.
>
> ### `paymentLinkId`
>
> `string | null`
>
> The public payment link ID, or null when the charge did not originate from a payment link. This is independent of the reason and recovery method.
>
> ### `recovery`
>
> `object | null`
>
> Null when the charge does not recover a subscription. payment\_recovery identifies a manually recovered overdue subscription, a return after cancellation for non-payment, or a retry of a failed subscription resume. Initial checkout and one-time payment retries are not recovery. dunning\_retry identifies an automatic charge retry, not a webhook delivery retry.
>
> ### `recovery.attempt`
>
> `integer`
>
> The charge retry position in the dunning schedule, starting at 1. The original failed charge is not a retry. Present only for dunning\_retry.
>
> ### `recovery.maxAttempts`
>
> `integer`
>
> The total automatic retries applicable to this charge when the attempt began. It is not the number of retries remaining. Present only for dunning\_retry.
>
> | reason | When it applies |
> | - | - |
> | `first_subscription_payment` | The initial subscription payment. |
> | `trial_conversion` | The payment when a free trial ends. |
> | `recurring_billing` | A subscription renewal. |
> | `plan_change` | A charge caused by a plan change. |
> | `reactivation` | A charge to reactivate a canceled subscription. |
> | `subscription_resume` | A charge to resume a paused subscription. |
> | `one_time_payment` | A one-time payment, including payment links. |
> | `overage` | A charge for usage beyond the included allowance. |
> | `adjustment` | A charge from an adjustment invoice. |

> [accordion] Initial attempt
>
> The original charge attempt, before recovery.
>
> ```json Initial attempt
> {
>   "event": "payment.failed",
>   "timestamp": "2026-06-23T14:30:00.000Z",
>   "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
>   "mode": "live",
>   "apiVersion": "2026-08-27",
>   "data": {
>     "paymentContext": {
>       "reason": "recurring_billing",
>       "paymentLinkId": null,
>       "recovery": null
>     },
>     "invoiceId": "inv_n4o5p6",
>     "invoiceNumber": "INV-0043",
>     "customerId": "user_123",
>     "subscriptionId": "sub_1a2b3c4d",
>     "provider": "stripe",
>     "paymentMethod": "card",
>     "subPaymentMethod": null,
>     "failureCode": "card_declined",
>     "failureMessage": "Your card was declined.",
>     "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
>   }
> }
> ```

> [accordion] Manual recovery
>
> The customer recovers an overdue subscription. The original charge reason is preserved.
>
> ```json Manual recovery
> {
>   "event": "payment.failed",
>   "timestamp": "2026-06-23T14:30:00.000Z",
>   "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
>   "mode": "live",
>   "apiVersion": "2026-08-27",
>   "data": {
>     "paymentContext": {
>       "reason": "recurring_billing",
>       "paymentLinkId": null,
>       "recovery": {
>         "type": "payment_recovery"
>       }
>     },
>     "invoiceId": "inv_n4o5p6",
>     "invoiceNumber": "INV-0043",
>     "customerId": "user_123",
>     "subscriptionId": "sub_1a2b3c4d",
>     "provider": "stripe",
>     "paymentMethod": "card",
>     "subPaymentMethod": null,
>     "failureCode": "card_declined",
>     "failureMessage": "Your card was declined.",
>     "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
>   }
> }
> ```

> [accordion] Dunning retries
>
> The second automatic retry of a subscription resume charge, out of four allowed retries. The reason remains subscription\_resume.
>
> ```json Dunning retries
> {
>   "event": "payment.failed",
>   "timestamp": "2026-06-23T14:30:00.000Z",
>   "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
>   "mode": "live",
>   "apiVersion": "2026-08-27",
>   "data": {
>     "paymentContext": {
>       "reason": "subscription_resume",
>       "paymentLinkId": null,
>       "recovery": {
>         "type": "dunning_retry",
>         "attempt": 2,
>         "maxAttempts": 4
>       }
>     },
>     "invoiceId": "inv_n4o5p6",
>     "invoiceNumber": "INV-0043",
>     "customerId": "user_123",
>     "subscriptionId": "sub_1a2b3c4d",
>     "provider": "stripe",
>     "paymentMethod": "card",
>     "subPaymentMethod": null,
>     "failureCode": "card_declined",
>     "failureMessage": "Your card was declined.",
>     "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
>   }
> }
> ```

> [accordion] No context
>
> The charge context was not captured. Do not infer the original reason from the subscription's current state.
>
> ```json No context
> {
>   "event": "payment.failed",
>   "timestamp": "2026-06-23T14:30:00.000Z",
>   "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
>   "mode": "live",
>   "apiVersion": "2026-08-27",
>   "data": {
>     "paymentContext": null,
>     "invoiceId": "inv_n4o5p6",
>     "invoiceNumber": "INV-0043",
>     "customerId": "user_123",
>     "subscriptionId": "sub_1a2b3c4d",
>     "provider": "stripe",
>     "paymentMethod": "card",
>     "subPaymentMethod": null,
>     "failureCode": "card_declined",
>     "failureMessage": "Your card was declined.",
>     "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
>   }
> }
> ```


## OpenAPI

````yaml /openapi/en/webhooks/2026-08-27.json webhook payment.failed
openapi: 3.1.0
info:
  title: Commet Webhooks
  version: '2026-08-27'
  description: >-
    Outbound webhook events emitted by the Commet API. Each event is delivered
    as a signed POST to your configured endpoints.
servers: []
security: []
paths: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.