# POST /api/v1/billing/voice-minutes

Auth: Bearer

HTML: https://cooperemail.com/docs/reference/set-voice-minutes

## Summary

Set how many 250-minute packs are on the subscription. Each pack is $10 per month, lookup key cooper_voice_250_monthly. packs replaces the previous quantity, from 0 to 100. A Starter or Pro subscription is required (HTTP 402 plan_limit_exceeded). A sub-account key returns HTTP 403 workspace_billing_forbidden. The route returns HTTP 404 not_found when voice billing is off, and HTTP 503 stripe_price_missing when that Price is not in Stripe. npm run stripe:setup does not create the price. Stripe prorates the change. The response is the new pack count.

## Request

```json
{
  "packs": 1
}
```

## Response

HTTP 200. Sample values illustrate the schema.

```json
{
  "object": "voice_minute_packs",
  "packs": 1,
  "previous_packs": 0,
  "minutes_per_pack": 250,
  "extra_minutes": 250,
  "monthly_cents": 1000,
  "lookup_key": "cooper_voice_250_monthly"
}
```

## Errors

- HTTP 402 plan_limit_exceeded
- HTTP 403 workspace_billing_forbidden
- HTTP 404 not_found
- HTTP 503 stripe_price_missing
- HTTP 403 permission_denied
- HTTP 503 voice_billing_failed

The live `message` is the sentence for that code. Branch on `code`.

```json
{
  "error": {
    "type": "payment_required",
    "code": "plan_limit_exceeded",
    "docs_url": "https://cooperemail.com/docs#plan_limit_exceeded"
  }
}
```

## Idempotency

This route does not document Idempotency-Key or client_id.