> ## Documentation Index
> Fetch the complete documentation index at: https://docs.statproxies.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace Proxy

> Replace a single proxy IP on an order with a new one.

Replace a single proxy IP on an order with a new, randomly selected available IP. The IP you pass must currently be assigned to the order. All other IPs on the order are untouched, and the proxy username, password, and port stay the same.

<Warning>
  This feature requires the `proxy_exchange` feature to be enabled for your organization. Without it, requests return **403 Forbidden**. Contact support if you need access. This endpoint only works on **active datacenter** orders (orders scheduled to cancel keep replace rights until they expire).
</Warning>

<Info>
  **Rate limits.** These calls trigger configuration reloads on the proxy servers, so they are limited two ways:

  * **Per order:** one replace per **60 seconds** (a **429** response includes `retry_after_seconds`).
  * **Per API key:** at most **10 exchange/replace calls per minute** combined, on top of the general 60 req/min limit.
</Info>

## Request

### Headers

| Header          | Value                   | Required |
| --------------- | ----------------------- | -------- |
| `Authorization` | `Bearer {your_api_key}` | Yes      |
| `Content-Type`  | `application/json`      | Yes      |

### Path Parameters

<ParamField path="order_id" type="string" required>
  The order ID returned from order creation.
</ParamField>

### Body Parameters

<ParamField body="ip" type="string" required>
  The IPv4 address to replace. Must currently belong to this order.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST "https://dashboard.statproxies.com/api/v2/order/replace/sub_1rqjp3jb4g9i6pkhdwmkpjob" \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"ip": "31.193.191.6"}'
```

## Response

### Success Response

```json theme={null}
{
  "response": "success",
  "message": "Proxy replaced successfully",
  "details": {
    "order_id": "sub_1rqjp3jb4g9i6pkhdwmkpjob",
    "old_ip": "31.193.191.6",
    "new_ip": "31.193.191.42",
    "new_proxy": "31.193.191.42:3128:sub_1rqjp3jb4g9i6pkhdwmkpjob:stat261"
  }
}
```

### Response Fields

<ResponseField name="response" type="string">
  Status of the request.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable result message.
</ResponseField>

<ResponseField name="details" type="object">
  Replace operation details.
</ResponseField>

<ResponseField name="details.order_id" type="string">
  The order ID that was processed.
</ResponseField>

<ResponseField name="details.old_ip" type="string">
  The IP that was removed from the order.
</ResponseField>

<ResponseField name="details.new_ip" type="string">
  The newly assigned IP.
</ResponseField>

<ResponseField name="details.new_proxy" type="string">
  The full proxy string for the new IP in `ip:port:username:password` format.
</ResponseField>

### Error Responses

#### 400 Bad Request - Missing Field

```json theme={null}
{
  "response": "error",
  "message": "Missing required field: ip"
}
```

#### 400 Bad Request - Invalid IP Format

```json theme={null}
{
  "response": "error",
  "message": "Invalid IP format"
}
```

#### 400 Bad Request - IP Not On Order

```json theme={null}
{
  "response": "error",
  "message": "The specified IP is not assigned to this order"
}
```

#### 400 Bad Request - Order Not Active

```json theme={null}
{
  "response": "error",
  "message": "Can only replace proxies for active or cancelled (not yet expired) orders"
}
```

Same rule as exchange: scheduled-to-cancel orders keep replace rights until expiry.

#### 400 Bad Request - Wrong Product Type

```json theme={null}
{
  "response": "error",
  "message": "Proxy replacement is only available for datacenter products"
}
```

#### 403 Forbidden - Feature Not Enabled

```json theme={null}
{
  "response": "error",
  "message": "Proxy exchange feature is not enabled for your organization."
}
```

#### 404 Not Found

```json theme={null}
{
  "response": "error",
  "message": "Order not found or you don't have permission to access it"
}
```

#### 429 Too Many Requests - Rate Limited

```json theme={null}
{
  "response": "error",
  "message": "An IP on this order was just replaced. You can replace another in N second(s).",
  "retry_after_seconds": 42
}
```

One replace per order is allowed every 60 seconds.

#### 500 Internal Server Error

```json theme={null}
{
  "response": "error",
  "message": "Failed to unassign the old IP"
}
```

Nothing changed; retry or contact support.

```json theme={null}
{
  "response": "error",
  "message": "The old IP was removed but a replacement could not be assigned. Please retry or contact support."
}
```

## Notes

* The proxy username, password, and port are unchanged — only one IP is swapped
* To replace **every** IP on the order at once, use [Exchange Proxies](/api-reference/order/exchange-proxies)
* Use [Get Order](/api-reference/order/get-order) to look up the current IPs assigned to an order

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Exchange Proxies" icon="arrows-rotate" href="/api-reference/order/exchange-proxies">
    Replace all IPs on an order at once.
  </Card>

  <Card title="Get Order" icon="download" href="/api-reference/order/get-order">
    Fetch the current proxy list for an order.
  </Card>
</CardGroup>