---
title: "Re-buy the plan on a package (adds a full plan of GB and one period)"
method: POST
path: "/proxies/{id}/renew"
tags: ["Proxies"]
---

# Re-buy the plan on a package (adds a full plan of GB and one period)

`POST /proxies/{id}/renew`

## Request

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

Adds one full plan allocation of GB on top of whatever is left and
extends `expires_at` by one plan period (from now if the package had
already lapsed). Accepted on `active`, `exhausted`, and `expired`
packages within 7 days of expiry; the package is `active` afterwards
and the traffic webhooks are re-armed. Charged at the plan's current
price; refunded automatically on failure.

On a pool-backed sub-order (`proxy.pool_id` set), renew instead
re-allocates the sub-order's **original** GB and duration from the
pool - not one plan period - at no incremental wallet charge.
`max_price_cents` is ignored. See the `Proxy pools` tag.

On a Standard dedicated proxy, renew extends an `active` proxy by one
term of its own plan, from the current `expires_at`, at the price it
was bought at with your current discount. `max_price_cents` is
required and checked before charging. An expired dedicated proxy
cannot be renewed (`409 PROXY_EXPIRED`); a Premium one returns
`422 NOT_SUPPORTED`. `proxy.renewed` fires on success.

## Path parameters

- `id` string, required: Opaque proxy package identifier.

## Headers

- `Idempotency-Key` string, required

## Request body

- RenewProxyRequest
  - `max_price_cents` integer: Required for a catalog (plan-backed) package; ignored for a pool-backed sub-order, where GB is drawn from the pool instead.

## Response `200`

Renewed; new `expires_at` reflected on the proxy. `pool_gb_charged` is present when the order is pool-backed.

- object
  - `success` true, required
  - `data` object, required
    - `proxy` Proxy, required
      - `id` string, required: Opaque proxy package identifier.
      - `display_id` string, nullable: Human-facing order reference shown in the dashboard. Quote it in support tickets.
      - `status` 'provisioning' | 'active' | 'expired' | 'refunded' | 'exhausted', required
      - `type` 'shared' | 'dedicated_standard' | 'dedicated_premium': `shared` is a mobile/GB package; the others are dedicated proxies.
      - `country` string, nullable: Lowercase ISO code of a dedicated proxy's location. Null for mobile/GB packages.
      - `carrier` string, nullable: Mobile carrier of a dedicated proxy. Null for mobile/GB packages.
      - `plan_id` string: Public plan identifier.
      - `pool_id` string: Opaque reseller GB pool identifier.
      - `data_gb_total` integer, required: Always 0 for dedicated proxies (unmetered).
      - `data_bytes_used` integer, required
      - `charged_price_cents` integer, required: What the purchase charged, after any discount. Renewals and top-ups are not included.
      - `expires_at` string, date-time, required
      - `auto_renew` boolean: Whether the proxy renews itself before `expires_at`. Settable on Standard dedicated proxies via `POST /v1/proxies/{id}/auto_renew`.
      - `next_renewal_price_cents` integer, nullable: What a renewal (manual or auto-renew) charges right now, with your current discount - pass it as `max_price_cents` to `POST /v1/proxies/{id}/renew`. Null when the proxy cannot be renewed over the API at the moment (pool sub-order, Premium dedicated, dedicated not active or its plan no longer sold, package past its renewal window).
      - `gateway` ProxyGateway, required: Connection details. For a mobile/GB package this is the package-level Flex gateway: geo, session stickiness, and rotation are controlled per request via underscore-prefixed parameters appended to `username` (see the proxies docs reference), and `username_geo_hint` is present. For an active Standard dedicated proxy it is the modem's own connection: `username` is used as-is, `port` is the HTTP port and `socks_port` is present.
        - `host` string, required
        - `port` integer, required: Mobile/GB gateway port, or a dedicated proxy's HTTP port.
        - `protocol` 'http', required
        - `username` string, required: Mobile/GB: base username. Append parameters per request, e.g. `<username>_c_US_s_session-1_ttl_5m` for a 5-minute sticky US session. Dedicated: the proxy username, used as-is.
        - `password` string, required
        - `username_geo_hint` string: Mobile/GB only. Short hint pointing at the parameter syntax. The docs are authoritative.
        - `socks_port` integer, nullable: Dedicated only. SOCKS5 port on the same host with the same credentials; null when the proxy has none.
      - `lists` ProxyList[], required
        - `id` string, required: Identifier for a per-list configuration inside a proxy package.
        - `proxy_id` string, required: Opaque proxy package identifier.
        - `name` string, required
        - `country` string, nullable
        - `countries` string[], nullable
        - `region` string, nullable
        - `city` string, nullable
        - `isp` string, nullable
        - `zip` string, nullable
        - `rotation_period_seconds` integer, required
        - `rotation_mode` 'instant' | 'delayed_5s' | 'no_rotation_on_fail', required
        - `format` 'login_pass_host_port' | 'http_url' | 'socks5_url' | 'host_port_login_pass_colon' | 'login_pass_host_port_colon' | 'host_port_login_pass_comma' | 'login_pass_host_port_at', required: Saved credential-format preference for the dashboard's list export. API `entries` are always `login:pass@host:port`. Each value names the exported line: - `login_pass_host_port`: `login:pass@host:port` - `http_url`: `http://login:pass@host:port` - `socks5_url`: `socks5://login:pass@host:port` - `host_port_login_pass_colon`: `host:port:login:pass` - `login_pass_host_port_colon`: `login:pass:host:port` - `host_port_login_pass_comma`: `host,port,login,pass` - `login_pass_host_port_at`: `login@pass@host@port` Deprecated names are still accepted on input but never returned: `host_port_login_pass` (= `host_port_login_pass_comma`), `host_port` (= `login_pass_host_port_colon`), `login_pass_at_host_port` (= `host_port_login_pass_colon`), `json` (= `login_pass_host_port_at`).
        - `credentials` ProxyCredentials, required
          - `host` string, required
          - `port` integer, required
          - `protocol` 'http', required
          - `username` string, required
          - `password` string, required
        - `entries` string[], required: Ready-to-paste connection strings in `login:pass@host:port` form, regardless of the saved `format` (which applies to the dashboard's list export). For IP-whitelist lists these are bare `host:port` strings. For SOCKS5, use the same host, port and credentials with a `socks5://` scheme; SOCKS5 also relays UDP, for QUIC (HTTP/3) to the target.
        - `network` string, nullable, required: Comma-separated IPv4 addresses/subnets whitelisted for this list, or null for login/password lists. Set when the list is created; immutable afterwards - delete and recreate the list to change it.
        - `activation_note` string, required: Operational hint to surface to the end user.
        - `created_at` string, date-time, required
      - `rotation_url` string, uri, nullable: Customer-facing rotation URL for dedicated proxies. A simple GET request to this URL rotates the exit IP, no auth header needed. Designed for anti-detect browser tools (AdsPower, GoLogin, Dolphin) that accept a "rotation URL" field. Null for shared (gb) proxies. The same 60s per-proxy cooldown applies as `POST /v1/proxies/:id/rotate_ip`. Regenerable from the dashboard if leaked.
      - `created_at` string, date-time, required
    - `pool_gb_charged` integer: GB drawn from the pool for this renewal. Present only when `proxy.pool_id` is set.

## Other responses

- `400`: 400 - Request failed validation.
- `402`: 402 - Your wallet balance is too low for this purchase.
- `404`: 404 - Proxy not found.
- `409`: Conflict - PRICE_MISMATCH (catalog or dedicated), PROXY_EXPIRED / PROXY_NOT_READY, or POOL_LAPSED / POOL_INSUFFICIENT_GB (pool-backed).
- `422`: 422 - This action is not supported.
- `502`: 502 - Proxy provisioning failed. Funds have been refunded.

---

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