--- title: "Balance" description: "5 operations, with parameters and examples." url: https://docs.fluveo.com/api/balance/ --- > Index of every page: https://docs.fluveo.com/llms.txt. Integrating Fluveo? Read https://docs.fluveo.com/agents/integrate.md first. > Too long? This page with code in one language only: https://docs.fluveo.com/api/balance.curl.md (cURL), https://docs.fluveo.com/api/balance.node.md (Node.js), https://docs.fluveo.com/api/balance.python.md (Python), https://docs.fluveo.com/api/balance.php.md (PHP). # Balance 5 operations, with parameters and examples. The Balance is the money the store holds, split into what is available to pay out and what is still pending. Two Fluveo extensions show how much may be paid out now and what holds a payout back. Send every request to `https://api.fluveo.com/v1` with your secret key as a Bearer token. This page lists only what Fluveo serves; [the OpenAPI file](https://docs.fluveo.com/openapi.json) holds the same operations. An operation or a parameter marked **Preview** works, but it is not locked yet and may change: [what Preview means](https://docs.fluveo.com/api.md#preview). > **For AI agents:** > > Use plain HTTP; install no payments SDK. Send `Authorization: Bearer sk_test_...` and a fresh `Idempotency-Key` on every POST; reuse the same key only when you retry that same POST. Send only the documented parameters. An operation or a parameter marked Preview may change: prefer the ones without the mark. ## Retrieves a balance `GET /v1/balance` Permission: [`rak_balance_read`](https://docs.fluveo.com/permissions.md#balance). **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a [`balance`](https://docs.fluveo.com/api/balance.md#object-balance) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/balance \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/balance", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/balance", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Updates the store's payout schedule: manual (a payout on request), or daily, weekly or monthly automatic payouts (Preview) `POST /v1/balance_settings` Permission: none. [No restricted key](https://docs.fluveo.com/permissions.md#no-restricted-key) may call this operation; only a secret key may. **Preview:** this operation works, but it is not locked yet; it may change. **Headers** - `Idempotency-Key` (string, optional): Send a unique key, 1 to 255 characters, on every POST. A retry with the same key and the same body returns the first answer instead of acting twice (with Idempotent-Replayed: true); the same key with another body is refused. Keys are kept 7 days, except on POST /v1/checkout/sessions, POST /v1/checkout/sessions/{session} and POST /v1/webhook_endpoints, where a key holds 24 hours; webhook endpoint keys are also capped at the newest 32 per store and mode. Do not rely on a replay after that window. GET and DELETE ignore it. - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. **Body parameters** - `payments` (object, optional): The payout schedule: payouts[schedule][interval] (manual, daily, weekly or monthly), with weekly_payout_days for weekly or monthly_payout_days for monthly. settlement_timing[delay_days_override] may only be sent empty; every other setting of the object is kept and refused. - `payouts` (object, optional) - `schedule` (object, optional) - `interval` (enum, optional): One of: `daily`, `manual`, `monthly`, `weekly`. - `monthly_payout_days` (array of integer, optional): The days of the month a monthly schedule pays out, each an integer from 1 to 31. - `weekly_payout_days` (array of string, optional) - `settlement_timing` (object, optional) - `delay_days_override` (integer, optional) Use only the documented body parameters. Send a new `Idempotency-Key` with each new request, and the same key again only to retry that request. Returns a [`balance_settings`](https://docs.fluveo.com/api/balance.md#object-balance_settings) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/balance_settings \ -H "Authorization: Bearer sk_test_..." \ -H "Idempotency-Key: $(uuidgen)" \ --data-urlencode "payments[payouts][schedule][interval]=weekly" \ --data-urlencode "payments[payouts][schedule][weekly_payout_days][]=friday" ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/balance_settings", { method: "POST", headers: { "Authorization": "Bearer sk_test_...", "Idempotency-Key": crypto.randomUUID(), }, body: new URLSearchParams([["payments[payouts][schedule][interval]","weekly"],["payments[payouts][schedule][weekly_payout_days][]","friday"]]), }); console.log(await response.json()); ``` Python: ```python import uuid import requests response = requests.post( "https://api.fluveo.com/v1/balance_settings", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())}, data=[("payments[payouts][schedule][interval]", "weekly"), ("payments[payouts][schedule][weekly_payout_days][]", "friday")], ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", "Idempotency-Key: " . bin2hex(random_bytes(16)), ], CURLOPT_POSTFIELDS => "payments%5Bpayouts%5D%5Bschedule%5D%5Binterval%5D=weekly&payments%5Bpayouts%5D%5Bschedule%5D%5Bweekly_payout_days%5D%5B%5D=friday", ]); echo curl_exec($ch); ``` ## Retrieves the store's balance settings: its payout schedule and the settlement delay (Preview) `GET /v1/balance_settings` Permission: none. [No restricted key](https://docs.fluveo.com/permissions.md#no-restricted-key) may call this operation; only a secret key may. **Preview:** this operation works, but it is not locked yet; it may change. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a [`balance_settings`](https://docs.fluveo.com/api/balance.md#object-balance_settings) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/balance_settings \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/balance_settings", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/balance_settings", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Reads how much the store may pay out right now, or zero with the reason (Preview) `GET /v1/balance/fluveo_payable_now` Permission: [`rak_balance_read`](https://docs.fluveo.com/permissions.md#balance). **Preview:** this operation works, but it is not locked yet; it may change. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. **Request** cURL: ```bash curl https://api.fluveo.com/v1/balance/fluveo_payable_now \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/balance/fluveo_payable_now", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/balance/fluveo_payable_now", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Reads the hold that stops a payout now, or null when nothing holds it (Preview) `GET /v1/balance/fluveo_payout_hold` Permission: [`rak_balance_read`](https://docs.fluveo.com/permissions.md#balance). **Preview:** this operation works, but it is not locked yet; it may change. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. **Request** cURL: ```bash curl https://api.fluveo.com/v1/balance/fluveo_payout_hold \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/balance/fluveo_payout_hold", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/balance/fluveo_payout_hold", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## The balance object **Attributes** - `available` (array) - `connect_reserved` (array) - `instant_available` (array) - `issuing` (object) - `livemode` (boolean) - `object` (enum): One of: `balance`. - `pending` (array) - `refund_and_dispute_prefunding` (object) ## The balance_settings object **Attributes** - `object` (enum): One of: `balance_settings`. - `payments` (object)