Reference

Usage reservations

A Usage Reservation holds usage before the work starts.

Checked 2026-09-28

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	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	Gets a usage reservation.
POST	settle	Settles a reservation with what was used; the unused part returns to headroom. A settle after expiry still records the usage.
POST	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

#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

#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

#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