---
title: "Set a cost threshold"
method: PUT
path: "/v1/cost-thresholds"
tags: ["Cost Thresholds"]
---

# Set a cost threshold

`PUT /v1/cost-thresholds`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/cost-thresholds`
- Auth: API key in header `x-api-key`

Sets what one person may spend per month on a usage type: for the organization, for a team (`teamId`), or for one user (`userId`). A new amount replaces the scope's current one on that usage type.

`VOICE` is international calling: once a user's spend reaches the threshold, international calls and SMS on their lines are paused until the next month, where their market offers the pause; elsewhere the threshold warns only. Other usage types answer `422` until the platform can enforce them.

The amount is in the team's cost-center currency, else the organization's primary; read it back from the response. The threshold opens now, so this month's spend counts against it at once, unless someone in scope has already spent more than the new amount: then it opens next month and `appliesFromNextMonth` says so. Raising it above a paused user's spend lifts their pause in the same call.

**Scope:** `policies:write`, and `teams:read` when a team is named.

## Headers

- `idempotency-key` string: A value unique to this request, of 1 to 255 printable ASCII characters — a UUID is the usual choice. Retry with the same key within 24 hours and you get the original response back, even if it was a failure, and nothing is done twice. Send a new key whenever you change the request. Keys are private to your API key and organisation.

## Request body

- object
  - `usageType` 'DATA' | 'VOICE' | 'SMS' | 'MMS', required: The usage type the threshold is on. `VOICE` is international calling: reaching it pauses international calls and SMS on the person's lines, where their market offers the pause. Other types answer `422` until the platform can enforce them.
  - `teamId` string, uuid: UUID of the team the threshold is for. Omit with `userId` for the organization's own.
  - `userId` string, uuid: UUID of the user the threshold is for. Omit with `teamId` for the organization's own.
  - `maxAmount` number, required: What one person may spend on the usage type per month, at most two decimals.

## Response `200`

The threshold as written, and what it did on the way in.

- SetCostThresholdResponse
  - `threshold` object, required: The threshold as written.
    - `id` string, required: UUID of the threshold.
    - `usageType` 'DATA' | 'VOICE' | 'SMS' | 'MMS', required: The usage type the threshold is on. `VOICE` is international calling: reaching it pauses international calls and SMS on the person's lines, where their market offers the pause. Other types answer `422` until the platform can enforce them.
    - `scope` 'organization' | 'team' | 'user', required: Whose threshold this is: the organization's default, a team's, or one user's own.
    - `teamId` string, nullable, required: The team, for a team threshold.
    - `userId` string, nullable, required: The user, for a user threshold.
    - `maxAmount` number, required: What one person may spend on the usage type per month, in `currency`.
    - `currency` string, required: ISO 4217 code of the threshold's money: the team's cost-center currency, else the organization's primary.
    - `period` 'monthly', required: The period the spend is counted in. Always the calendar month.
    - `validFrom` string, required: When the threshold opens (ISO 8601). A threshold lowered below someone's spend opens next month.
    - `validTo` string, nullable, required: When the threshold closes (ISO 8601), or null while it stands.
  - `appliesFromNextMonth` boolean, required: True when someone in scope has already spent more than the new amount this month, so it opens next month rather than now.
  - `releasedNumberCount` integer, required: Lines whose pause was lifted because the raised amount put their user back under it.

## Other responses

- `400`: Request failed schema validation, or named both a team and a user
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to manage policies
- `404`: No team in your organization has this id, so nothing was read or changed. No user in your organization has this id, so nothing was read or changed.
- `409`: Another write of the same threshold landed at the same moment, so this one was refused and nothing was changed.
- `422`: No cost center names a currency for this scope, so the threshold has no money to be written in. The cost-center currency is one no exchange rate covers, so spend could never be compared with a threshold in it. No threshold can stand on this usage type yet, so nothing was read or changed.
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)