# Update Auto Top-up Settings

Source: https://recoupable.dev/docs/api-reference/accounts/auto-top-up-update

Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; removing the card turns it off. `id` may be the authenticated account or an organization the caller belongs to.

## PUT /api/accounts/{id}/auto-top-up

Full OpenAPI specification: https://recoupable.dev/docs/spec/accounts.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Accounts",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/accounts/{id}/auto-top-up": {
      "put": {
        "description": "Set the auto top-up settings for an account. All three fields are required on every call; there is no partial update. Turning it on requires a card on file (`GET /api/accounts/{id}/payment-method` returns a card), an amount between 5.00 and 1,000.00 USD, and a threshold below the amount. Turning it off keeps the last amount and threshold so the account can turn it back on without retyping them. Guardrails that apply once it is on: at most one top-up per account per 10 minutes; a card decline turns `enabled` back to `false`, records `lastError`, and emails the account instead of retrying; removing the card turns it off. `id` may be the authenticated account or an organization the caller belongs to.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKeyAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Auto top-up settings",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAutoTopUpRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settings saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoTopUpResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid body, `enabled: true` without a card on file, `amountCents` outside 500..100000, `thresholdCents` negative, or `thresholdCents` not below `amountCents`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoTopUpErrorResponse"
                },
                "example": {
                  "error": "Add a payment method before turning on auto top-up"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoTopUpErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - the account is not the caller's and not an organization they belong to (an unknown id also returns 403, never 404)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoTopUpErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The account has no credits row and one could not be created for it",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoTopUpErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UpdateAutoTopUpRequest": {
        "type": "object",
        "required": [
          "enabled",
          "amountCents",
          "thresholdCents"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "amountCents": {
            "type": "integer",
            "minimum": 500,
            "maximum": 100000,
            "description": "Amount to charge and grant per top-up, in cents (5.00 to 1,000.00 USD).",
            "example": 10000
          },
          "thresholdCents": {
            "type": "integer",
            "minimum": 0,
            "description": "Balance, in cents, below which a top-up runs. Must be below `amountCents`.",
            "example": 100
          }
        }
      },
      "AutoTopUpResponse": {
        "type": "object",
        "required": [
          "account_id",
          "enabled",
          "amountCents",
          "thresholdCents",
          "lastRunAt",
          "lastError"
        ],
        "properties": {
          "account_id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether auto top-up is on. Off by default.",
            "example": true
          },
          "amountCents": {
            "type": "integer",
            "nullable": true,
            "description": "Amount charged and granted per top-up, in cents. Null until set.",
            "example": 10000
          },
          "thresholdCents": {
            "type": "integer",
            "nullable": true,
            "description": "Balance, in cents, below which a top-up runs. Null until set.",
            "example": 100
          },
          "lastRunAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the last auto top-up was attempted. Null until the first run.",
            "example": "2026-09-04T15:05:00Z"
          },
          "lastError": {
            "type": "string",
            "nullable": true,
            "description": "Stripe decline message from the attempt that turned auto top-up off. Null while healthy or once re-enabled.",
            "example": "Your card was declined."
          }
        }
      },
      "AutoTopUpErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message.",
            "example": "Add a payment method before turning on auto top-up"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```