--- title: "Reserves" description: "6 operations, with parameters and examples." url: https://docs.fluveo.com/api/reserves/ --- > 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/reserves.curl.md (cURL), https://docs.fluveo.com/api/reserves.node.md (Node.js), https://docs.fluveo.com/api/reserves.python.md (Python), https://docs.fluveo.com/api/reserves.php.md (PHP). # Reserves 6 operations, with parameters and examples. A reserve keeps part of a store's sales back for a time to cover refunds and disputes. Reserve plans, holds and releases are read-only views of the reserves on the store's account, the same routes, lists and fields for every store. A hold is released on its release date, or earlier when Fluveo's operators release it; a hold made on its own, with no sale, stays until Fluveo releases it. A change can also come as a reserve.* event (see Events). The balance's risk_reserved shows what the reserve holds. A store whose reserve follows no plan has an empty plans list. 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. > **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. ## Lists the amounts held back under the store's reserve plans, newest first. Filters: reserve_plan, is_releasable, currency, source_charge, reserve_release `GET /v1/reserve/holds` Permission: [`rak_reserve_read`](https://docs.fluveo.com/permissions.md#reserve). A Fluveo extension, listed under Fluveo extensions: not part of API version 2026-05-27.dahlia. Its objects are the reserve objects of the store's account. **Query parameters** - `currency` (string, optional): Only holds in this currency. - `ending_before` (string, optional): Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after. - `is_releasable` (string, optional): true for holds that may be released now, false for the others. - `limit` (integer, optional): How many objects to return, from 1 to 100. Default 10. - `reserve_plan` (string, optional): Only the holds of this reserve plan. - `reserve_release` (string, optional): Only the holds this reserve release released money from. - `source_charge` (string, optional): Only the holds taken from this charge (ch_...). - `starting_after` (string, optional): Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before. **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/reserve/holds \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/reserve/holds", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/reserve/holds", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Lists the reserve plans on the store's account. Filter: status `GET /v1/reserve/plans` Permission: [`rak_reserve_read`](https://docs.fluveo.com/permissions.md#reserve). A Fluveo extension, listed under Fluveo extensions: not part of API version 2026-05-27.dahlia. Its objects are the reserve objects of the store's account. **Query parameters** - `ending_before` (string, optional): Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after. - `limit` (integer, optional): How many objects to return, from 1 to 100. Default 10. - `starting_after` (string, optional): Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before. - `status` (string, optional): Filter by status. **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/reserve/plans \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/reserve/plans", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/reserve/plans", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Lists the releases of the store's reserve holds, newest first. Filters: reserve_hold, reserve_plan, currency `GET /v1/reserve/releases` Permission: [`rak_reserve_read`](https://docs.fluveo.com/permissions.md#reserve). A Fluveo extension, listed under Fluveo extensions: not part of API version 2026-05-27.dahlia. Its objects are the reserve objects of the store's account. **Query parameters** - `currency` (string, optional): Only releases in this currency. - `ending_before` (string, optional): Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after. - `limit` (integer, optional): How many objects to return, from 1 to 100. Default 10. - `reserve_hold` (string, optional): Only the releases of this reserve hold. - `reserve_plan` (string, optional): Only the releases of this reserve plan's holds. - `starting_after` (string, optional): Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before. **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/reserve/releases \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/reserve/releases", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/reserve/releases", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Retrieves one reserve hold. Expand: reserve_plan, source_charge `GET /v1/reserve/holds/{id}` Permission: [`rak_reserve_read`](https://docs.fluveo.com/permissions.md#reserve). A Fluveo extension, listed under Fluveo extensions: not part of API version 2026-05-27.dahlia. It is the retrieve half of the list and shows the object exactly as its list row. **Path parameters** - `id` (string, required): The reserve hold's id. **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/reserve/holds/reshold_123 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/reserve/holds/reshold_123", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/reserve/holds/reshold_123", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Retrieves one reserve plan of the store's account `GET /v1/reserve/plans/{id}` Permission: [`rak_reserve_read`](https://docs.fluveo.com/permissions.md#reserve). A Fluveo extension, listed under Fluveo extensions: not part of API version 2026-05-27.dahlia. It is the retrieve half of the list and shows the object exactly as its list row. **Path parameters** - `id` (string, required): The reserve plan's id. **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/reserve/plans/resplan_123 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/reserve/plans/resplan_123", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/reserve/plans/resplan_123", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Retrieves one reserve release. Expand: reserve_plan, reserve_hold `GET /v1/reserve/releases/{id}` Permission: [`rak_reserve_read`](https://docs.fluveo.com/permissions.md#reserve). A Fluveo extension, listed under Fluveo extensions: not part of API version 2026-05-27.dahlia. It is the retrieve half of the list and shows the object exactly as its list row. **Path parameters** - `id` (string, required): The reserve release's id. **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/reserve/releases/resrel_123 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/reserve/releases/resrel_123", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/reserve/releases/resrel_123", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ```