--- title: "Update a spend limit" method: PATCH path: "/spend_limits/{product}" tags: ["Spend Limits"] --- # Update a spend limit `PATCH /spend_limits/{product}` ## Request - Base URL: `https://api.telnyx.com/v2` - URL: `https://api.telnyx.com/v2/spend_limits/{product}` - Auth: HTTP bearer Replaces the value of the existing limit for the product and period. Send exactly one of `amount` and `unlimited: true`. The period's spend is checked at once: raising the limit above the spend lifts the period's block (`evaluation.released`), and lowering it below the spend blocks the product (`evaluation.blocked_now`). Returns 404 when no limit is set; create it instead. With the `credential_id` query parameter, the request changes that API key's limit; it needs an `amount`, and raising it is subject to the allocation rule. ## Path parameters - `product` string, required ## Query parameters - `period` 'daily' | 'monthly': `daily` is the current UTC day; `monthly` is the current UTC calendar month. - `credential_id` string ## Request body - union: Send exactly one of `amount` and `unlimited: true`. - UpdateSpendLimitWithAmount: A new limit in USD. - `amount` number, required: Limit in USD. `0` blocks at the first cent of spend. - `unlimited` false: Optional; only `false` is allowed together with `amount`. - `reason` string: Why the limit is set or changed, kept for audit. - UpdateSpendLimitUnlimited: Explicitly no cap. - `unlimited` true, required: `true`: explicitly no cap. - `reason` string: Why the limit is set or changed, kept for audit. ## Response `200` The limit was updated. `evaluation` says whether the change lifted or started a block. - SpendLimitResponse - `data` SpendLimit, required: The spend limit, spend and block state of one product and period. The top-level fields describe the total limit of the account; API key limits are nested in `credential_limits`. - `record_type` string, required: Identifies the type of the resource. - `product` string, required: Product the entry applies to. - `product_name` string, required: Display name of the product. - `period` 'daily' | 'monthly', required: `daily` is the current UTC day; `monthly` is the current UTC calendar month. - `period_start` string, date, required: First UTC day of the current period. - `period_end` string, date, required: Exclusive end of the current period, a UTC date. - `credential_id` string, nullable: In write responses, the API key the write was about; `null` for the total limit. Always `null` in list entries, which describe the total limit. - `limit` SpendLimitLimit, nullable, required: The limit set on the account for the product and period, whoever set it. `null` when none is set. - `amount` string, nullable, required: Limit in USD, as a decimal string. `null` when `unlimited` is true. - `unlimited` boolean, required: True when the limit was set to explicitly no cap. - `origin` 'self_service' | 'operator', required: `self_service` when a user of the account set it, `operator` when Telnyx support did. - `updated_at` string, date-time, required: When the limit was last set or changed. - `effective_limit_usd` string, nullable, required: The limit in USD that is enforced, as a decimal string. `null` means unlimited. - `spend_usd` string, nullable, required: Spend in USD so far in the period, as a decimal string. It can lag actual usage by about a minute. `null` when it could not be read. - `spend_error` string, nullable, required: Set when `spend_usd` is `null`. - `blocked` boolean, required: The product is blocked for the whole account in this period (total limit). An API key's own block appears only in `credential_limits`. Always `false` in write responses; list the limits to read the block state. - `block` SpendLimitBlock, nullable, required: The active block of the period. `null` when the period is not blocked. - `detected_at` string, date-time, required: When the block started. - `spend_usd` string, required: Spend in USD when the block started, as a decimal string. - `limit_usd` string, required: The limit in USD that the spend went above, as a decimal string. - `blocked_until` string, date, required: Exclusive end of the block: it is lifted at 00:00 UTC on this date at the latest. - `allocation` SpendLimitAllocation, nullable: How much of the period's total limit is given to API key limits. `null` unless the period has a total limit with an amount. - `total_limit_usd` string, required: The total limit in USD, as a decimal string. - `allocated_usd` string, required: Sum of the period's API key limits in USD, as a decimal string. - `unallocated_usd` string, required: The part of the total not given to API key limits, as a decimal string: the largest amount a new API key limit can have. - `over_allocated_usd` string, required: How far the API key limits exceed the total, as a decimal string. Non-zero only after Telnyx support lowered the total below them. - `credential_limits` SpendLimitCredentialLimit[]: List responses only. One item per API key limit of the product and period, sorted by `credential_id`, plus every API key that is still blocked. `[]` when there are none. - `credential_id` string, required: Identifier of the API key as recorded on usage. Never the key's secret. - `limit` SpendLimitCredentialLimitValue, nullable, required: The limit of one API key. It always has an amount. `null` for an API key that is still blocked after its limit was removed. - `amount` string, required: Limit in USD, as a decimal string. - `origin` 'self_service' | 'operator', required: `self_service` when a user of the account set it, `operator` when Telnyx support did. - `updated_at` string, date-time, required: When the limit was last set or changed. - `spend_usd` string, nullable, required: Spend in USD in the period made with exactly this API key, as a decimal string. Usage without an API key identifier, or with another one, counts only toward the total. `null` when it could not be read. - `spend_error` string, nullable, required: Set when `spend_usd` is `null`. - `blocked` boolean, required: This API key is blocked for the period. - `block` SpendLimitBlock, nullable, required: The active block of the period. `null` when the period is not blocked. - `detected_at` string, date-time, required: When the block started. - `spend_usd` string, required: Spend in USD when the block started, as a decimal string. - `limit_usd` string, required: The limit in USD that the spend went above, as a decimal string. - `blocked_until` string, date, required: Exclusive end of the block: it is lifted at 00:00 UTC on this date at the latest. - `evaluation` SpendLimitEvaluation: What a create, update or delete did to the period at once. Only present in write responses. - `spend_usd` string, nullable, required: Spend in USD used for the check, as a decimal string. `null` when the spend was not checked. - `released` boolean, required: The change lifted a block of this period. - `blocked_now` boolean, required: The change blocked the product: the spend was already above the new limit. - `still_over_limit` boolean, required: A block of this period remains because the spend is still above the new limit. - `still_blocked_other_period` boolean, required: The other period has an active block, so the product stays blocked whatever this period's result. For an API key write, the API key's limit in the other period. - `account_blocked` boolean: API key writes only: the account itself remains blocked for the product under a total limit. Absent for total limit writes. - `evaluation_deferred` boolean, required: The spend could not be checked now. The change is saved and applied within a few minutes. - `note` string: Additional information about the result, when there is any. ## Other responses - `400`: Bad request. The product does not support self-service spend limits, the period is invalid or not available, not exactly one of `amount` and `unlimited` was sent, `amount` is negative, `reason` is longer than 500 characters, or the body has a field that is not listed. For an API key limit (`credential_id`): API key limits are not available for the product or period, `credential_id` is invalid, `unlimited` was sent, or the period's API key limits would add up to more than the total limit. Lowering the total limit below the sum of the period's API key limits is refused too. - `401`: Unauthorized. The request did not carry valid Telnyx API credentials. - `403`: Forbidden. The caller's access policy does not allow this spend limits action. - `404`: Not found. No spend limit is set for the product and period, or for the API key. ## Changes - **2026-10-22** `4de6bba1c49d`: 5 info - added the new optional `query` request parameter `credential_id` - added the optional property `data/allocation` to the response with the `200` status - added the optional property `data/credential_id` to the response with the `200` status - added the optional property `data/credential_limits` to the response with the `200` status - …1 more - **2026-10-15** `a72569d69430`: 1 info - endpoint added [Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/spend_limits/:product/patch.md) --- [API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/0f17b8167873?raw)