---
title: "Toggle auto-renew for a dedicated number"
method: POST
path: "/dedicated/numbers/{id}/auto_renew"
tags: ["Dedicated Numbers"]
---

# Toggle auto-renew for a dedicated number

`POST /dedicated/numbers/{id}/auto_renew`

## Request

- Base URL: `https://dashboard.voidmob.com/api/v1`
- URL: `https://dashboard.voidmob.com/api/v1/dedicated/numbers/{id}/auto_renew`
- Auth: HTTP bearer

Sets auto-renew to the specified state for a dedicated number owned by the
authenticated user. Unlike a flip toggle, this is idempotent - calling with
the same `enabled` value twice is safe.

Turning auto-renew off after the next period was already charged refunds
that charge to your balance. If the renewal is already under way, the call
returns `400 VALIDATION_ERROR` ("This number is already renewing and the
next term is paid. Turn auto-renew off after it renews.") and auto-renew
stays on.

Some UK, Hong Kong and Indonesia renewals are locked in during the last
days of the period. Turning auto-renew off then returns
`400 VALIDATION_ERROR` ("Auto-renew can't be turned off this close to the
renewal. This term will renew."). Turning it on then renews the number
right away, so the next period is charged first; without enough balance
the call returns `402 INSUFFICIENT_BALANCE` and nothing changes.

## Path parameters

- `id` string, required

## Request body

- object
  - `enabled` boolean, required: Set to `true` to enable auto-renew, `false` to disable.

## Response `200`

Auto-renew state updated. Returns the updated dedicated number.

- object
  - `success` true, required
  - `data` object, required
    - `id` string, required: Dedicated number id prefixed `ded_`.
    - `display_id` string, nullable: Human-readable display id.
    - `status` 'active' | 'expired', required
    - `phone_number` string, required: Full E.164 phone number.
    - `country` string, required: Lowercase ISO-2 country code.
    - `country_name` string, required: Human-readable country name.
    - `billing_period` 'monthly', required
    - `nickname` string, nullable: User-set nickname for this number.
    - `quoted_price_cents` integer, required: Price quoted at purchase time in USD cents.
    - `charged_price_cents` integer, required: Price actually charged in USD cents.
    - `next_renewal_price_cents` integer, required: Price that will be charged on next renewal in USD cents.
    - `payment_due` PaymentDue, required: A renewal that landed before it could be paid. The term is renewed but owed; the amount is collected automatically as soon as the balance covers it. SMS received meanwhile are withheld (`content_withheld`) until it is paid, and stay withheld if the term ends unpaid.
      - `amount_cents` integer, required: Amount owed, in USD cents.
      - `since` string, date-time, required: When the renewal landed unpaid.
    - `auto_renew` boolean, required: Whether this number auto-renews at period end.
    - `created_at` string, date-time, required
    - `paid_until` string, date-time, required: Date through which the number is paid.
    - `expires_at` string, date-time, required
    - `messages` object[], required: Always empty in this response.
      - `id` string, required
      - `code` string, nullable
      - `text` string, nullable, required
      - `content_withheld` true
      - `received_at` string, date-time, required

## Other responses

- `400`: 400 - Request failed validation.
- `401`: 401 - Authentication required.
- `402`: 402 - Your wallet balance is too low for this purchase.
- `404`: 404 - The requested resource was not found.
- `429`: 429 - Rate limit exceeded. Retry after the indicated interval.
- `502`: 502 - Service error. Please retry shortly.
- `503`: 503 - Service is currently unavailable.

---

[API](https://skmtc.dev/voidmob/apis/voidmob-public-api.md) · [All operations](https://skmtc.dev/voidmob/apis/voidmob-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voidmob/apis/voidmob-public-api/revisions/066023313ebe?raw)