Balance

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 holds the same operations.

An operation or a parameter marked Preview works, but it is not locked yet and may change: what Preview means.

Retrieves a balance#

GET/v1/balancerak_balance_read

Headers

Fluveo-VersionenumOptional
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 object.

Request

curl https://api.fluveo.com/v1/balance \
  -H "Authorization: Bearer sk_test_..."

const response = await fetch("https://api.fluveo.com/v1/balance", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_...",
  },
});
console.log(await response.json());

import requests

response = requests.get(
    "https://api.fluveo.com/v1/balance",
    headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())

<?php
$ch = curl_init("https://api.fluveo.com/v1/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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 payoutsPreview#

POST/v1/balance_settingsNo restricted key

Preview: this operation works, but it is not locked yet; it may change.

Headers

Idempotency-KeystringOptional
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-VersionenumOptional
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

paymentsobjectOptional
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.
2 child fields
- payoutsobjectOptional
  1 child field
  - scheduleobjectOptional
    3 child fields
    intervalenumOptional
    One of: daily, manual, monthly, weekly.
    monthly_payout_daysarray of integerOptional
    The days of the month a monthly schedule pays out, each an integer from 1 to 31.
    weekly_payout_daysarray of stringOptional
- settlement_timingobjectOptional
  1 child field
  - delay_days_overrideintegerOptional

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 object.

Request

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"

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());

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
$ch = curl_init("https://api.fluveo.com/v1/balance_settings");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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 delayPreview#

GET/v1/balance_settingsNo restricted key

Preview: this operation works, but it is not locked yet; it may change.

Headers

Fluveo-VersionenumOptional
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 object.

Request

curl https://api.fluveo.com/v1/balance_settings \
  -H "Authorization: Bearer sk_test_..."

const response = await fetch("https://api.fluveo.com/v1/balance_settings", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_...",
  },
});
console.log(await response.json());

import requests

response = requests.get(
    "https://api.fluveo.com/v1/balance_settings",
    headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())

<?php
$ch = curl_init("https://api.fluveo.com/v1/balance_settings");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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 reasonPreview#

GET/v1/balance/fluveo_payable_nowrak_balance_read

Preview: this operation works, but it is not locked yet; it may change.

Headers

Fluveo-VersionenumOptional
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 https://api.fluveo.com/v1/balance/fluveo_payable_now \
  -H "Authorization: Bearer sk_test_..."

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());

import requests

response = requests.get(
    "https://api.fluveo.com/v1/balance/fluveo_payable_now",
    headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())

<?php
$ch = curl_init("https://api.fluveo.com/v1/balance/fluveo_payable_now");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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 itPreview#

GET/v1/balance/fluveo_payout_holdrak_balance_read

Preview: this operation works, but it is not locked yet; it may change.

Headers

Fluveo-VersionenumOptional
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 https://api.fluveo.com/v1/balance/fluveo_payout_hold \
  -H "Authorization: Bearer sk_test_..."

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());

import requests

response = requests.get(
    "https://api.fluveo.com/v1/balance/fluveo_payout_hold",
    headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())

<?php
$ch = curl_init("https://api.fluveo.com/v1/balance/fluveo_payout_hold");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_...",
    ],
]);
echo curl_exec($ch);

The balance object#

Attributes

availablearray
connect_reservedarray
instant_availablearray
issuingobject
livemodeboolean
objectenum
One of: balance.
pendingarray
refund_and_dispute_prefundingobject

The balance_settings object#

Attributes

objectenum
One of: balance_settings.
paymentsobject