---
title: "API reference"
description: "Every operation of the Fluveo /v1 API, generated from the code: parameters, examples, errors and events. Preview marks what is not locked yet."
url: https://docs.fluveo.com/api/
---

> Index of every page: https://docs.fluveo.com/llms.txt. Integrating Fluveo? Read https://docs.fluveo.com/agents/integrate.md first.

# API reference

Every operation of the Fluveo /v1 API, generated from the code: parameters, examples, errors and events. Preview marks what is not locked yet.

The Fluveo /v1 API, generated from the code that serves it. These pages describe documented parameters; they are not an exhaustive allow-list. Call it over plain HTTP; install no payments SDK.

| What | Value |
| --- | --- |
| Base URL | `https://api.fluveo.com/v1` |
| Authentication | `Authorization: Bearer sk_test_...`, the store's secret key |
| Request body | `application/x-www-form-urlencoded`, nested keys as `metadata[order_id]=1042` |
| Idempotency | `Idempotency-Key` on every POST, 1 to 255 characters, kept 7 days; 24 hours on `POST /v1/checkout/sessions`, `POST /v1/checkout/sessions/{session}` and `POST /v1/webhook_endpoints`, where webhook endpoint keys are also capped at the newest 32 per store and mode |
| API version | `2026-05-27.dahlia` is the only one; send no `Fluveo-Version` header |
| Amounts | integers in the smallest unit of the currency: `2000` is 20.00 |
| Lists | `limit` 1 to 100 (default 10), cursors `starting_after` and `ending_before` |

> **For AI agents:**
>
> Never send a header that acts for another account, card numbers, `transfer_data`, `on_behalf_of` or `application_fee_amount`: Fluveo refuses them. Branch on `error.code`, never on `error.message`.

## Preview

An operation or a parameter marked **Preview** works today, but it is not locked yet, so it may change. What has no mark is locked. Today 61 of 115 operations are in preview.

> **For AI agents:**
>
> Prefer operations and parameters without the Preview mark: a preview works, but it may change.

## Resources

- [PaymentIntents](https://docs.fluveo.com/api/payment_intents.md): 8 operations, with parameters and examples.
- [Charges](https://docs.fluveo.com/api/charges.md): 4 operations, with parameters and examples.
- [Refunds](https://docs.fluveo.com/api/refunds.md): 6 operations, with parameters and examples.
- [Disputes](https://docs.fluveo.com/api/disputes.md): 4 operations, with parameters and examples.
- [Early fraud warnings](https://docs.fluveo.com/api/early_fraud_warnings.md): 2 operations, with parameters and examples.
- [PaymentMethods](https://docs.fluveo.com/api/payment_methods.md): 7 operations, with parameters and examples.
- [Customers](https://docs.fluveo.com/api/customers.md): 10 operations, with parameters and examples.
- [Products](https://docs.fluveo.com/api/products.md): 6 operations, with parameters and examples.
- [Prices](https://docs.fluveo.com/api/prices.md): 5 operations, with parameters and examples.
- [Balance](https://docs.fluveo.com/api/balance.md): 5 operations, with parameters and examples.
- [Balance transactions](https://docs.fluveo.com/api/balance_transactions.md): 2 operations, with parameters and examples.
- [Payouts](https://docs.fluveo.com/api/payouts.md): 5 operations, with parameters and examples.
- [Reserves](https://docs.fluveo.com/api/reserves.md): 6 operations, with parameters and examples.
- [Events](https://docs.fluveo.com/api/events.md): 2 operations, with parameters and examples.
- [Webhook endpoints](https://docs.fluveo.com/api/webhook_endpoints.md): 5 operations, with parameters and examples.
- [Checkout Sessions](https://docs.fluveo.com/api/checkout_sessions.md): 6 operations, with parameters and examples.
- [SetupIntents](https://docs.fluveo.com/api/setup_intents.md): 7 operations, with parameters and examples.
- [Payment links](https://docs.fluveo.com/api/payment_links.md): 5 operations, with parameters and examples.
- [Wallets](https://docs.fluveo.com/api/wallets.md): 10 operations, with parameters and examples.
- [Files and file links](https://docs.fluveo.com/api/files.md): 7 operations, with parameters and examples.
- [Account](https://docs.fluveo.com/api/account.md): 3 operations, with parameters and examples.

## Objects

The API's messages link to these objects here; each one's attributes are on its resource page.

### The `balance` object

[The `balance` object](https://docs.fluveo.com/api/balance.md#object-balance) lists its attributes.

### The `token` object

[The `token` object](https://docs.fluveo.com/api/wallets.md#object-token) lists its attributes.

## Errors and events

- [Errors](https://docs.fluveo.com/errors.md): Every error code the API returns, with its HTTP status and what to do.
- [Event types](https://docs.fluveo.com/webhooks/events.md): Every event type Fluveo sends to your webhook endpoints, and the object it carries.
- [Permissions](https://docs.fluveo.com/permissions.md): What each restricted key permission allows, and the permission every operation needs.