---
title: "Update spend caps"
description: "Set, raise, lower or clear a monthly spend cap; only the caps you send change. `PATCH /api/v1/spend-caps`"
url: https://www.unitpost.com/docs/platform/patch-spend-caps
section: "Platform API reference"
updated: 2026-11-17
---
# Update spend caps

`PATCH /api/v1/spend-caps`

Set, raise, lower or clear a monthly spend cap; only the caps you send change. `sms_purchases.cap_cents` is whole cents from 0 (API purchases off) to the platform maximum ($1,000 a month by default), or null to clear it, after which every API purchase is refused (`403 api_spend_cap_not_set`) until a cap is set again. A purchase over the cap is refused with `403 api_spend_cap_exceeded` and nothing is charged; the dashboard buys past it. The capability is in no key preset, and only the workspace owner holds it and can give it to a key or an app; no other capability changes a cap. A workspace its organization pays for refuses it (`403 billed_by_organization`): its organization sets that cap with `sms_purchases_cap_cents` on `PATCH /organizations/{id}/workspaces/{workspace_id}`. `shared_plan` is read-only: a body naming it is `403 billed_by_organization` and changes nothing (the organization sets that cap with `PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`). Requires the `spend_caps:write` capability.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sms_purchases` | object | no | — |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | — |
| `sms_purchases` | object | yes | SMS purchases by API (`POST /sms/quotes/{id}/confirm`). Purchases made in the dashboard never count. |
| `shared_plan` | object \| null | no | The workspace's cap on its organization's shared plan, read-only: its organization sets it (`PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`). Null when the workspace isn't on a shared plan. |

## Responses

| Status | Description |
| --- | --- |
| 200 | The spend caps, after the change. |
| 400 | The body isn't JSON. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope (`spend_caps:write`), a workspace its organization pays for (`billed_by_organization`), or a body naming `shared_plan` (`billed_by_organization`: its organization sets it). |
| 404 | SMS is not enabled. |
| 422 | A cap outside 0 to the platform maximum or not whole cents, no cap to change, or an unknown key. |

## Example request

```bash
curl -X PATCH 'https://www.unitpost.com/api/v1/spend-caps' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
```

## Example response (200)

```json
{
  "object": "spend_caps",
  "sms_purchases": {
    "cap_cents": 0,
    "max_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  },
  "shared_plan": {
    "cap_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  }
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/platform/patch-spend-caps
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json
