Auto Top-Up Failed

Fired when an automatic top-up is blocked, declined, or fails before granting additional prepaid balance.

WEBHOOK billing.auto_topup_failed

Example

{
  "type": "billing.auto_topup_failed",
  "data": {
    "customer_id": "cus_123",
    "feature_id": "messages",
    "reason": "charge_failed",
    "quantity": 100,
    "threshold": 20,
    "balance": 15,
    "invoice_mode": false,
    "error": {
      "code": "card_declined",
      "message": "Your card was declined.",
      "type": "card_error",
      "decline_code": "generic_decline"
    }
  }
}

Payload Fields

customer_id · string · required

The ID of the customer whose auto top-up failed.

feature_id · string · required

The feature ID that Autumn attempted to auto top-up.

reason · 'charge_failed' | 'purchase_limit_reached' | 'attempt_limit_reached' | 'failed_attempt_limit_reached' | 'suspended_after_failures' | 'customer_unavailable' | 'configuration_unavailable' | 'missing_payment_method' | 'missing_customer_product' | 'invalid_amount' | 'lock_contention' | 'redis_unavailable' | 'execution_error' · required

Machine-readable reason the automatic top-up did not grant balance.

quantity · number | null

The normalized amount of balance Autumn attempted to grant, when a matching auto top-up config was available.

threshold · number | null

The configured balance threshold for the auto top-up, when available.

balance · number | null

The customer’s remaining balance for the feature at the time the failure was detected, when available.

invoice_mode · boolean | null

Whether the auto top-up was configured to create a send_invoice invoice instead of auto-charging.

error · object | null

Sanitized provider or Autumn error metadata, when the failure came from an exception or declined charge.

Show properties

code · string | null

Machine-readable error code when one is available (for example, a Stripe or Autumn error code).

message · string | null

Sanitized error message with details about why the auto top-up failed.

type · string | null

Provider error type when one is available.

decline_code · string | null

Stripe decline code when the failure came from a card decline.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

type · string · required

The webhook event type.

Allowed value: "billing.auto_topup_failed"

data · object · required

Show child attributes

Example:

{
  "customer_id": "cus_123",
  "feature_id": "messages",
  "reason": "charge_failed",
  "quantity": 100,
  "threshold": 20,
  "balance": 15,
  "invoice_mode": false,
  "error": {
    "code": "card_declined",
    "message": "Your card was declined.",
    "type": "card_error",
    "decline_code": "generic_decline"
  }
}

Response

200

Webhook received successfully.