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

# Auto Top-Up Failed

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

### Payload Fields

<ParamField body="customer_id" type="string" required>
  The ID of the customer whose auto top-up failed.
</ParamField>

<ParamField body="feature_id" type="string" required>
  The feature ID that Autumn attempted to auto top-up.
</ParamField>

<ParamField body="reason" type="'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.
</ParamField>

<ParamField body="quantity" type="number | null">
  The normalized amount of balance Autumn attempted to grant, when a matching auto top-up config was available.
</ParamField>

<ParamField body="threshold" type="number | null">
  The configured balance threshold for the auto top-up, when available.
</ParamField>

<ParamField body="balance" type="number | null">
  The customer's remaining balance for the feature at the time the failure was detected, when available.
</ParamField>

<ParamField body="invoice_mode" type="boolean | null">
  Whether the auto top-up was configured to create a send\_invoice invoice instead of auto-charging.
</ParamField>

<ParamField body="error" type="object | null">
  Sanitized provider or Autumn error metadata, when the failure came from an exception or declined charge.

  <Expandable title="properties">
    <ParamField body="code" type="string | null">
      Machine-readable error code when one is available (for example, a Stripe or Autumn error code).
    </ParamField>

    <ParamField body="message" type="string | null">
      Sanitized error message with details about why the auto top-up failed.
    </ParamField>

    <ParamField body="type" type="string | null">
      Provider error type when one is available.
    </ParamField>

    <ParamField body="decline_code" type="string | null">
      Stripe decline code when the failure came from a card decline.
    </ParamField>
  </Expandable>
</ParamField>


## OpenAPI

````yaml api/openapi.yml webhook billing.auto_topup_failed
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.3.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths: {}
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````