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

# Update Auto Top-up Settings

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



## OpenAPI

````yaml api-reference/openapi/accounts.json PUT /api/accounts/{id}/auto-top-up
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
security: []
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
      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'
      security:
        - apiKeyAuth: []
        - bearerAuth: []
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

````