---
title: "Enable or disable auto-renew on a rental"
method: POST
path: "/rentals/{id}/auto_renew"
tags: ["Rentals"]
---

# Enable or disable auto-renew on a rental

`POST /rentals/{id}/auto_renew`

## Request

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

Sets the `auto_renew` flag to an explicit state. Unlike a toggle,
calling with the same `enabled` value twice is safe (idempotent by
construction). No `Idempotency-Key` header is required.

When `enabled: true`, the rental will automatically renew for the same
duration at expiry, charged to your balance shortly before
`paid_until`. When `enabled: false`, the rental expires normally when
`expires_at` is reached.

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

Returns `400 VALIDATION_ERROR` if the rental has already expired.

## Path parameters

- `id` string, required: Opaque long-term rental identifier.

## Headers

- `Idempotency-Key` string

## Request body

- RentalAutoRenewRequest
  - `enabled` boolean, required: `true` to enable auto-renew; `false` to disable. Explicit state (not a toggle) - calling with the same value twice is safe.

## Response `200`

Auto-renew preference updated. Returns the updated rental.

- object
  - `success` true, required
  - `data` object, required
    - `id` string, required: Opaque long-term rental identifier.
    - `display_id` string, nullable: Human-readable order identifier for display in dashboards and receipts (e.g. `SMS7K4P2N`). Null for legacy rows.
    - `status` 'active' | 'expired' | 'cancelled', required
    - `phone_number` string, required: E.164 phone number (with leading +).
    - `service_id` string, required: Opaque public service identifier.
    - `service_name` string, required: Human-readable service name.
    - `country` string, required: ISO-3166-1 alpha-2, lowercased.
    - `duration` '3D' | '7D' | '14D' | '30D', required: Rental period.
    - `rental_type` 'rental', required: Always `rental` for long-term rentals.
    - `charged_price_cents` integer, required: Actual amount deducted from the wallet.
    - `pricing_source` 'regular' | 'category' | 'override' | 'promo': Attribution for the charged price. Omitted for legacy rows. "promo" means a redeemed service-discount code priced this purchase.
    - `auto_renew` boolean, required: Whether the rental will automatically renew at expiry.
    - `next_renewal_price_cents` integer, required: Estimated cost of the next auto-renewal at current pricing.
    - `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.
    - `re_rent_available` boolean, required: Whether this rental is eligible for re-rent on the same number after it expires. `true` only when the rental is `expired` and the number has not yet been released. `false` for all non-expired rentals and for expired rentals that are no longer eligible.
    - `re_rent_price_cents` integer, nullable, required: Current re-rent price in USD cents. Non-null only when `re_rent_available` is `true`. Null for all other states.
    - `re_rent_blocked_at` string, date-time, nullable, required: ISO 8601 timestamp at which the number was permanently released. Non-null means re-rent will never become available for this rental. Null when still eligible (or for non-expired rentals).
    - `created_at` string, date-time, required
    - `paid_until` string, date-time, required: Timestamp through which the number is paid.
    - `expires_at` string, date-time, required: Timestamp at which the rental expires (same as `paid_until` for standard rentals).
    - `can_cancel` boolean, required: Whether the rental is currently cancellable. True only within the first hour after creation and only for non-dedicated rentals that have not been flagged.
    - `cancel_window_expires_at` string, date-time, nullable: Timestamp at which the cancel window closes. Null for dedicated 28-day numbers (which cannot be cancelled).
    - `messages` RentalMessage[], required: SMS messages received on this number, sorted oldest-first. A message received while payment is due has `text` and `code` null and `content_withheld: true`.
      - `id` string, required: Opaque message identifier (prefixed `msg_`).
      - `code` string, nullable: Extracted numeric code, if any. Null when the SMS is informational or its content is withheld.
      - `text` string, nullable, required: Full raw SMS text. Null only while the content is withheld.
      - `content_withheld` true: Present (always `true`) only on an SMS received while a renewal is unpaid (`payment_due`): stored, but `text` and `code` are null until the due is paid. Absent on every other message.
      - `received_at` string, date-time, required

## Other responses

- `400`: 400 - Request failed validation.
- `401`: 401 - Authentication required.
- `404`: 404 - The requested resource was not found.
- `429`: 429 - Rate limit exceeded. Retry after the indicated interval.
- `500`: 500 - An unexpected error occurred. Please try again.
- `502`: 502 - Service error. Please retry shortly.

---

[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)