--- title: "Check and reserve flag" method: POST path: "/flags/{key}/check-and-reserve" tags: ["features"] --- # Check and reserve flag `POST /flags/{key}/check-and-reserve` ## Path parameters - `key` string, required ## Request body - CheckAndReserveFlagRequestBody - `company` object, nullable - `expires_at` string, date-time, nullable — When the hold lapses if no track event settles it; defaults to one minute from now and may be at most one hour out. The unspent hold is refunded on expiry - `idempotency_key` string, nullable — A caller-chosen key for safe retries: a second request with the same key returns the original reservation instead of taking another hold - `preflight` PreflightRequestBody - `credit_cost` object — Cost in credits of the action, keyed by credit ID, for callers that have already computed it. Takes precedence over usage and event_usage on credit balance conditions for the same credit. A cost of zero means the action is free, not that the input is absent - `event_usage` PreflightEventUsageRequestBody - `event_subtype` string, required — The event subtype the usage would be recorded under - `quantity` integer, required — How many units of the event subtype the action would record. Zero has no effect - `usage` integer, nullable — Quantity of usage to simulate against any numeric condition encountered while evaluating the flag. Zero has no effect - `quantity` number, double, nullable — Units of the feature the operation will consume. Sets the hold size together with the entitlement's consumption rate, and is echoed back on the reservation for the settling track event. When it is omitted the units come from preflight.event_usage.quantity, if that event subtype is the entitlement's, else from preflight.usage, else 1 - `user` object, nullable ## Response `200` OK - object - `data` CheckAndReserveFlagResponseData, required - `company_id` string, nullable — If company keys were provided and matched a company, its ID - `entitlement` FeatureEntitlement - `allocation` integer, nullable — If the company has a numeric entitlement for this feature, the allocated amount - `consumption_rate` number, double, nullable — If the company has a credit-based entitlement for this feature, the credit cost per unit of usage - `credit_id` string, nullable — If the company has a credit-based entitlement for this feature, the ID of the credit - `credit_remaining` number, double, nullable — If the company has a credit-based entitlement for this feature, the credit available to fund new consumption or a new lease hold — open lease holds are excluded. Clients that hold a lease should gate on this plus their own unspent hold; clients with no lease awareness should use credit_settled instead - `credit_reserved` number, double, nullable — If the company has a credit-based entitlement for this feature, the unspent amount held by an open credit lease. Returns to credit_remaining when the lease is released - `credit_settled` number, double, nullable — If the company has a credit-based entitlement for this feature, the balance net of actual consumption, unaffected by open lease holds (credit_remaining plus credit_reserved). The number to display to end users - `credit_total` number, double, nullable — If the company has a credit-based entitlement for this feature, the total credit amount - `credit_used` number, double, nullable — If the company has a credit-based entitlement for this feature, the amount of credit used - `event_name` string, nullable — If the feature is event-based, the name of the event tracked for usage - `event_subtype` string, nullable — For event-based or credit-metered feature entitlements, the event subtype whose usage is tracked - `feature_id` string, required — The ID of the feature - `feature_key` string, required — The key of the flag associated with the feature - `metric_period` 'all_time' | 'current_day' | 'current_month' | 'current_week' - `metric_reset_at` string, date-time, nullable — For event-based feature entitlements, when the usage period will reset - `month_reset` 'billing_cycle' | 'first_of_month' - `soft_limit` integer, nullable — For usage-based pricing, the soft limit for overage charges or the next tier boundary - `usage` integer, nullable — If the company has a numeric entitlement for this feature, the current usage amount - `value_type` 'boolean' | 'credit' | 'numeric' | 'trait' | 'unknown' | 'unlimited', required - `warning_tiers` WarningTier[] — Customer-defined usage warning thresholds configured on this entitlement - `key` string, required — A customer-defined identifier for the warning tier - `value` integer, required — The warning threshold, in the entitlement's usage units - `error` string, nullable — If an error occurred while checking the flag, the error message - `feature_allocation` integer, nullable — Deprecated: Use Entitlement.Allocation instead. - `feature_usage` integer, nullable — Deprecated: Use Entitlement.Usage instead. - `feature_usage_event` string, nullable — Deprecated: Use Entitlement.EventName instead. - `feature_usage_period` 'all_time' | 'current_day' | 'current_month' | 'current_week' - `feature_usage_reset_at` string, date-time, nullable — Deprecated: Use Entitlement.MetricResetAt instead. - `flag` string, required — The key used to check the flag - `flag_id` string, nullable — If a flag was found, its ID - `reason` string, required — A human-readable explanation of the result - `reservation` FlagCheckReservationResponseData - `company_id` string, required - `consumption_rate` number, double, required — Credits per unit of usage the hold was priced at - `credit_type_id` string, required - `credits_reserved` number, double, required — Credits held from the company's balance - `event_subtype` string, nullable — The event subtype the settling track event should carry - `expires_at` string, date-time, required — When the unspent hold is refunded if no track event settles it - `id` string, required - `quantity_reserved` number, double, required — Units of usage the hold covers, as requested - `rule_id` string, nullable — If a rule was found, its ID - `rule_type` 'company_override' | 'company_override_usage_exceeded' | 'default' | 'global_override' | 'plan_entitlement' | 'plan_entitlement_usage_exceeded' | 'standard' - `user_id` string, nullable — If user keys were provided and matched a user, its ID - `value` boolean, required — A boolean flag check result; for feature entitlements, this represents whether further consumption of the feature is permitted - `params` object, required — Input parameters ## Other responses - `400` — Bad request - `401` — Unauthorized - `403` — Forbidden - `404` — Not found - `500` — Server error ## Changes - **2026-09-17** `5206bbdb2682` — 1 info - added the new optional request property `idempotency_key` - **2026-09-17** `d2fb8bb90eaf` — 1 warning - the `quantity` request property's max was set to `9999999999.00` - **2026-09-14** `1ce13450aec3` — 1 info - endpoint added [Change history](https://skmtc.dev/schematichq/apis/schematic-api/changes/flags/:key/check-and-reserve/post.md) --- [API](https://skmtc.dev/schematichq/apis/schematic-api.md) · [All operations](https://skmtc.dev/schematichq/apis/schematic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/schematichq/apis/schematic-api/revisions/a56c23fa7dbe?raw)