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

# Top up sandbox balance

> Sets the available + total balance on the Business's sandbox Cleff Account so it can exercise payouts, without the dev CLI. Sandbox only: refused with SANDBOX_ONLY (409) on a production session, which can never touch a real wallet. The account must already be provisioned.



## OpenAPI

````yaml POST /v1/business/funding-account/sandbox-balance
openapi: 3.0.0
info:
  title: Cleff API
  description: >-
    Payout orchestration platform. All endpoints under /v1/ require an API key
    in the Authorization header (Bearer ck_<env>_<id>_<secret>).
  version: 0.0.1
  contact: {}
servers: []
security: []
tags: []
paths:
  /v1/business/funding-account/sandbox-balance:
    post:
      tags:
        - Funding
      summary: Top up the current Business's sandbox Cleff Account (sandbox only)
      description: >-
        Sets the available + total balance on the Business's sandbox Cleff
        Account so it can exercise payouts, without the dev CLI. Sandbox only:
        refused with SANDBOX_ONLY (409) on a production session, which can never
        touch a real wallet. The account must already be provisioned.
      operationId: SandboxBalanceController_setBalance
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetSandboxBalanceDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DedicatedAccountDto'
        '401':
          description: Missing or invalid credentials
        '403':
          description: Caller lacks permission for this action
        '409':
          description: Production session (SANDBOX_ONLY) or account not provisioned
      security:
        - api_key: []
components:
  schemas:
    SetSandboxBalanceDto:
      type: object
      properties:
        available_balance_minor:
          type: number
          description: Available balance to set, in minor units. Max 9007199254740991.
          maximum: 9007199254740991
        total_balance_minor:
          type: number
          description: Total balance to set, in minor units. Max 9007199254740991.
          maximum: 9007199254740991
        currency:
          type: string
          description: ISO 4217 currency code; defaults to the account currency.
      required:
        - available_balance_minor
        - total_balance_minor
    DedicatedAccountDto:
      type: object
      properties:
        currency:
          type: string
        available_balance_minor:
          type: number
          description: Available balance, in minor units.
        total_balance_minor:
          type: number
          description: Total balance, in minor units.
        status:
          type: string
          enum:
            - pending
            - active
            - suspended
          description: >-
            Neutral account status derived server-side: 'pending' until the
            provider first reports, 'active' thereafter, 'suspended' when
            frozen.
        reported_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Instant Cleff last applied a balance report from the provider — the
            balance is only as fresh as this. Always Cleff's own clock, whether
            the provider pushed the balance or Cleff polled for it, so it is
            directly comparable with the timestamps on your payouts. A report
            that arrives out of order is discarded and does not move this. Null
            until the first report lands (status 'pending').
        deposit_instructions:
          nullable: true
          description: >-
            The coordinates the Business funds this account with; absent on
            non-Checkbook paths.
          allOf:
            - $ref: '#/components/schemas/DepositInstructionsDto'
      required:
        - currency
        - available_balance_minor
        - total_balance_minor
        - status
        - reported_at
        - deposit_instructions
    DepositInstructionsDto:
      type: object
      properties:
        bank_name:
          type: string
          nullable: true
          description: Display-only bank name; may be absent.
        routing_number:
          type: string
        account_number:
          type: string
        account_holder_name:
          type: string
          nullable: true
          description: Display-only account holder name; may be absent.
        reference:
          type: string
          nullable: true
          description: Optional memo to tag inbound deposits with for reconciliation.
      required:
        - bank_name
        - routing_number
        - account_number
        - account_holder_name
        - reference
  securitySchemes:
    api_key:
      scheme: bearer
      bearerFormat: ck_<env>_<id>_<secret>
      type: http
      description: >-
        Cleff API key issued to a Business that self-registers via POST
        /v1/registration

````