API REFERENCE

Update Auto Top-up Settings

On this page

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

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.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request PUT \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/auto-top-up' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "enabled": true,
  "amountCents": 10000,
  "thresholdCents": 100
}'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

idstringrequired

The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.

Request body required

Auto top-up settings

application/json

enabledbooleanrequired

amountCentsintegerrequired

Amount to charge and grant per top-up, in cents (5.00 to 1,000.00 USD).

minimum: 500 · maximum: 100000

thresholdCentsintegerrequired

Balance, in cents, below which a top-up runs. Must be below amountCents.

minimum: 0

Responses

200Settings saved.

application/json

account_idstringrequired

format: uuid

enabledbooleanrequired

Whether auto top-up is on. Off by default.

amountCentsintegerrequirednullable

Amount charged and granted per top-up, in cents. Null until set.

thresholdCentsintegerrequirednullable

Balance, in cents, below which a top-up runs. Null until set.

lastRunAtstringrequirednullable

When the last auto top-up was attempted. Null until the first run.

format: date-time

lastErrorstringrequirednullable

Stripe decline message from the attempt that turned auto top-up off. Null while healthy or once re-enabled.

400Bad request - invalid body, enabled: true without a card on file, amountCents outside 500..100000, thresholdCents negative, or thresholdCents not below amountCents

application/json

errorstringrequired

Human-readable error message.

400 example

{
  "error": "Add a payment method before turning on auto top-up"
}

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

401 example

{
  "error": "Unauthorized"
}

403Forbidden - the account is not the caller's and not an organization they belong to (an unknown id also returns 403, never 404)

application/json

errorstringrequired

Human-readable error message.

404The account has no credits row and one could not be created for it

application/json

errorstringrequired

Human-readable error message.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json

View operation source

json

{
  "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"
          }
        }
      }
    }
  }
}