Skip to main content
WEBHOOK
billing.auto_topup_failed
{
  "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' | '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.

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
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.