API REFERENCE

Get Auto Top-up Settings

On this page

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

Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for amountCents the first time a credit deduction leaves the balance below thresholdCents, then grants the credits and emails a receipt. 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 GET \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/auto-top-up' \
  --header 'x-api-key: YOUR_API_KEY'

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.

Responses

200Auto top-up settings (defaults when never configured).

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.

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.

Full specification

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

Download accounts.json

View operation source

json

{
  "description": "Read the auto top-up settings for an account. Auto top-up is opt-in: it is off for every account until the account turns it on and chooses both the amount to buy and the balance that triggers it. When it is on, the api charges the default card on file for `amountCents` the first time a credit deduction leaves the balance below `thresholdCents`, then grants the credits and emails a receipt. `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": []
    }
  ],
  "responses": {
    "200": {
      "description": "Auto top-up settings (defaults when never configured).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AutoTopUpResponse"
          }
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}