---
# @generated by sylphx-gen 0.1.0 from contracts@190f1b33b937c1aef79697684018db853389b521c75e19ff69ac6af609e96f45. Do not edit.
title: "Usage reservations"
description: "The `usage_reservations` collection of Sylphx Money: A Usage Reservation holds usage before the work starts."
type: reference
product: payments
summary: "A Usage Reservation holds usage before the work starts."
updated: 2026-09-28
order: 900
---

A Usage Reservation holds usage before the work starts. Settling it records what was used and releases the rest; releasing it records nothing.

**Service** Sylphx Money · **Resource type** `money.sylphx.com/UsageReservation` · **Name pattern** `orgs/{org}/projects/{project}/envs/{env}/usage_reservations/{usage_reservation}` · **Shape** `record`

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | `orgs/{org}/projects/{project}/envs/{env}/usage_reservations/{usage_reservation}`. |
| `uid` | `string` | `ures_<cell><ulid>`; never reused. Output only. |
| `meta` | `ResourceMeta` | Resource metadata. |
| `subject` | `Subject` | Who uses it. Required. |
| `subject_proof` | `string` | The acting end user's access token, required on every reserve: Money proves the subject itself, fresh, with the caller's own key (`auth:sessions:verify`) or the merchant's configured issuer. Never stored. A raw id is refused with PERMISSION_DENIED (reason `subject_unverified`). Required. |
| `actor_proof` | `string` | For a customer organization: the token of the acting user, whose membership of the organization is checked fresh. The subject is Sylphx Auth's bare organization id (`acme`), never a resource name. Never stored. |
| `meter` | `string` | The meter's lookup key. Required. |
| `max_quantity` | `int64` | The most the work may use, in the meter's base unit. Required. |
| `ttl` | `duration` | How long the hold lasts, at most `600s`; default `600s`. |
| `granted_quantity` | `int64` | What was granted: at most `max_quantity`, less under headroom. Output only. |
| `state` | `string` | `held`, `settled`, or `released`. Output only. |
| `expire_time` | `timestamp` | When the hold ends. Output only. |
| `dark_refusal` | `string` | While enforcement is dark: why it would have been refused (`spend_limit_reached`, `no_payment_method`, `account_suspended`); empty otherwise. Output only. |

## Methods

Every method of the collection, in the registry's order, with the scope it
needs. The full request, response and examples are one link away.

| Method | Call | What it does |
| --- | --- | --- |
| `POST` | [`create`](/docs/api/usage_reservations#create) | Reserves usage before the work starts. Refused with PLAN_LIMIT_REACHED (spend limit, no payment method) or INVALID_STATE (suspended) only while enforcement is on; while it is dark the reservation is granted and the refusal is recorded. |
| `GET` | [`get`](/docs/api/usage_reservations#get) | Gets a usage reservation. |
| `POST` | [`settle`](/docs/api/usage_reservations#settle) | Settles a reservation with what was used; the unused part returns to headroom. A settle after expiry still records the usage. |
| `POST` | [`release`](/docs/api/usage_reservations#release) | Releases a reservation that used nothing. |

## create

Reserves usage before the work starts. Refused with PLAN_LIMIT_REACHED (spend limit, no payment method) or INVALID_STATE (suspended) only while enforcement is on; while it is dark the reservation is granted and the refusal is recorded.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_reservations` · scope `billing:metering:write` · effect `write` · [Request, response and examples](/docs/api/usage_reservations/create)

## get

Gets a usage reservation.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_reservations/usage-reservation` · scope `billing:read` · effect `read` · [Request, response and examples](/docs/api/usage_reservations/get)

## settle

Settles a reservation with what was used; the unused part returns to headroom. A settle after expiry still records the usage.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_reservations/usage-reservation:settle` · scope `billing:metering:write` · effect `write` · [Request, response and examples](/docs/api/usage_reservations/settle)

## release

Releases a reservation that used nothing.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_reservations/usage-reservation:release` · scope `billing:metering:write` · effect `write` · [Request, response and examples](/docs/api/usage_reservations/release)