Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

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; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. 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.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

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

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

Example: true

amountCentsintegerrequired

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

Example: 10000

minimum: 500 · maximum: 100000

thresholdCentsintegerrequired

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

Example: 100

minimum: 0

Responses

200Settings saved.

application/json

account_idstringrequired

Example: "550e8400-e29b-41d4-a716-446655440000"

format: uuid

enabledbooleanrequired

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

Example: true

amountCentsintegerrequirednullable

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

Example: 10000

thresholdCentsintegerrequirednullable

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

Example: 100

lastRunAtstringrequirednullable

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

Example: "2026-09-04T15:05:00Z"

format: date-time

lastErrorstringrequirednullable

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

Example: "Your card was declined."

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.

Example: "Add a payment method before turning on auto top-up"

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.

Example: "Add a payment method before turning on auto top-up"

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.

Example: "Add a payment method before turning on auto top-up"

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

application/json

errorstringrequired

Human-readable error message.

Example: "Add a payment method before turning on auto top-up"

Full specification

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

Download accounts.json
View operation source
json
{
  "operationId": "putAccountsByIdAutoTopUp",
  "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; a successful selected-card removal turns it off before detachment, even when other saved cards remain. Removal does not cancel a charge already in progress. `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"
          }
        }
      }
    }
  }
}