---
title: "Turn monthly renewal of a number on or off"
method: PUT
path: "/api/v1/phone-numbers/{did}/auto-renew"
tags: ["Phone numbers"]
---

# Turn monthly renewal of a number on or off

`PUT /api/v1/phone-numbers/{did}/auto-renew`

## Request

- Base URL: `https://wardenpoint.com` (the document declares no server; this is the origin it was published from)
- URL: `https://wardenpoint.com/api/v1/phone-numbers/{did}/auto-renew`
- Auth: API key in header `X-API-Key`

Costs nothing by itself but decides the number's fate: with renewal on, the monthly cost is charged to the credit balance each month; with it off, the number stops working at `expires_at` and is given up at the provider. Turning it back on before expiry restores the schedule; after expiry the number is gone and would have to be bought again, if it is even still on offer. The flag is required — omitting it is not read as false, because silently switching renewal off on a number the caller never mentioned looks like a vanished number a month later rather than a bad request. PATCH is accepted on the same path with identical semantics.

## Path parameters

- `did` string, uuid, required

## Request body

- object
  - `auto_renew` boolean, required: Required. True keeps charging monthly, false lets the number lapse at expiry.

## Response `200`

The number, with the new flag.

- object
  - `data` PhoneNumber: An external number the company owns. Unlike every other object in this API it disappears on its own when it stops being paid for, so `expires_at`, `auto_renew` and `renewal_failures` are part of its normal reading, not diagnostics.
    - `uuid` string, uuid: Stable identifier — every phone-number endpoint takes this.
    - `number` string: E.164.
    - `country_code` string, nullable
    - `city` string, nullable
    - `number_type` 'local' | 'mobile' | 'tollfree' | 'national', nullable: Kind of number, as classified when it was bought.
    - `status` 'assigned' | 'pending_purchase' | 'suspended': `assigned` — live. `pending_purchase` — the provider has not confirmed yet. `suspended` — three renewal charges in a row failed; the number no longer carries calls and cannot be made the default caller ID until it is paid for. Those three are the only ones the listing returns; the column also holds `available`, `reserved` and `retired`, which mean the number is not the company's any more.
    - `monthly_cost` number, float: Charged to the company credit balance every month while `auto_renew` is on.
    - `currency` string
    - `auto_renew` boolean: True keeps charging `monthly_cost` to the credit balance each month. False lets the number lapse at `expires_at`, after which it stops carrying calls and leaves the company.
    - `is_default` boolean: Whether outbound calls present this number. Exactly one number per company can hold it.
    - `expires_at` string, date-time, nullable: End of the paid period. With auto_renew on this is the next charge date, not a deadline; with it off, the moment the number stops working.
    - `is_expiring_soon` boolean: True within five days of expiry.
    - `renewal_failures` integer: Consecutive failed renewal charges. At three the number goes `suspended`. A non-zero value means the credit balance did not cover the charge.
    - `created_at` string, date-time

## Other responses

- `401`: API key missing, invalid, revoked or expired.
- `403`: API key lacks the config.write ability, or the number belongs to another company.
- `404`: No number with this UUID.
- `422`: auto_renew missing or not a boolean.
- `429`: Too many number changes in a short window.

---

[API](https://skmtc.dev/wardenpoint/apis/wardenpoint-api.md) · [All operations](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/revisions/259ee445728e?raw)