> ## 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.

# Exchange Proxies

> Replace all IP addresses in an order with new ones, optionally swapping to a different product.

Exchange all proxies on an order — every assigned IP is released and a fresh set of the same quantity is allocated, preferring servers that did not hold your previous IPs.

The endpoint also supports **cross-product exchange**: send a target product and the same quantity is reassigned from a different datacenter pool. Omit the body (or send `{}`) to exchange within the same pool with unchanged behavior.

<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 exchange 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 exchange per **15 minutes** (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`      | Only for cross-product exchange |

### Path Parameters

<ParamField path="order_id" type="string" required>
  The order ID for which to exchange proxies.
</ParamField>

### Body Parameters

The body is optional. Omit it (or send `{}`) for a same-pool exchange. To exchange into a different datacenter pool, provide the target product:

<ParamField body="target_product_type" type="string">
  The datacenter pool to move the order into. Supported values: `sprint`, `captcha`, `events`, `lumen`. The aliases `product_type` and `target_product_id` are also accepted.
</ParamField>

### Example Request

Same-pool exchange (unchanged behavior):

```bash theme={null}
curl -X POST "https://dashboard.statproxies.com/api/v2/order/exchange/sub_1rqjp3jb4g9i6pkhdwmkpjob" \
  -H "Authorization: Bearer {your_api_key}"
```

Cross-product exchange:

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

The aliases `product_type` and `target_product_id` accept the same value:

```json theme={null}
{ "product_type": "captcha" }
```

```json theme={null}
{ "target_product_id": "captcha" }
```

## Response

### Success Response

```json theme={null}
{
  "response": "success",
  "message": "Proxies exchanged successfully",
  "details": {
    "order_id": "sub_1rqjp3jb4g9i6pkhdwmkpjob",
    "previous_count": 10,
    "new_count": 10,
    "requested_count": 10,
    "overlapping_ips": 0,
    "previous_product_type": "sprint",
    "product_type": "captcha",
    "proxy_port": 3128
  }
}
```

For a same-pool exchange, `previous_product_type` and `product_type` are identical.

### 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">
  Exchange operation details.
</ResponseField>

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

<ResponseField name="details.previous_count" type="integer">
  Number of IPs before the exchange.
</ResponseField>

<ResponseField name="details.new_count" type="integer">
  Number of IPs after the exchange.
</ResponseField>

<ResponseField name="details.requested_count" type="integer">
  Number of IPs requested (based on order quantity).
</ResponseField>

<ResponseField name="details.overlapping_ips" type="integer">
  Number of IPs that are the same between old and new (should be 0 ideally).
</ResponseField>

<ResponseField name="details.previous_product_type" type="string">
  The product the order was on before the exchange. Matches `product_type` for a same-pool exchange.
</ResponseField>

<ResponseField name="details.product_type" type="string">
  The product the order is on after the exchange.
</ResponseField>

<ResponseField name="details.proxy_port" type="integer">
  The proxy port for the order's current product.
</ResponseField>

### Error Responses

#### 403 Forbidden - Feature Not Enabled

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

#### 404 Not Found

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

#### 400 Bad Request - Order Not Active

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

Orders scheduled to cancel keep exchange rights until they expire; only expired or terminated orders are refused.

#### 400 Bad Request - Wrong Product Type

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

#### 429 Too Many Requests - Rate Limited

```json theme={null}
{
  "response": "error",
  "message": "Proxies for this order were exchanged recently. You can exchange again in about N minute(s).",
  "retry_after_seconds": 840
}
```

One exchange per order is allowed every 15 minutes. The `retry_after_seconds` field tells you how long to wait.

#### 500 Internal Server Error

```json theme={null}
{
  "response": "error",
  "message": "Internal server error during proxy exchange"
}
```

## How It Works

<Steps>
  <Step title="Request Exchange">
    You call the exchange endpoint with your order ID.
  </Step>

  <Step title="Current IPs Removed">
    All current proxy IPs are removed from the servers.
  </Step>

  <Step title="New IPs Assigned">
    Fresh IPs from the available pool are assigned to your order.
  </Step>

  <Step title="Confirmation">
    The response confirms the exchange with before/after counts.
  </Step>
</Steps>

## Requirements

* **Active order**: The order must be active, or cancelled but not yet expired (orders scheduled to cancel keep exchange rights until expiration)
* **Datacenter product**: Exchange is only available for datacenter proxy products
* **Feature enabled**: Your organization must have the `proxy_exchange` feature enabled
* **Within rate limits**: One exchange per order every 15 minutes, and at most 10 exchange/replace calls per minute per API key

## Use Cases

* **IP blocked**: Get fresh IPs if your current ones are blocked
* **Clean slate**: Start with unused IPs for a new project
* **Rotation**: Periodic IP rotation for long-running operations

## Notes

* The exchange process takes a few seconds to complete
* Your proxy username and password remain the same
* The new IPs will be different from your previous ones (overlap should be 0)
* A same-pool exchange does not affect your billing or subscription
* To swap a **single** IP instead of the whole set, use [Replace Proxy](/api-reference/order/replace-proxy)

### Cross-product exchange safety

When moving an order to a different product, the operation is fully atomic:

* If the target pool cannot fully assign the requested quantity, the old proxies, the order record, and the Stripe subscription are **all left unchanged**.
* Stripe is updated **only after** the new target proxies are fully assigned.
* Source proxies are deleted **only after** target assignment and the Stripe update both succeed.

## Getting Access

If you need the proxy exchange feature enabled for your organization:

<Card title="Contact Support" icon="envelope" href="mailto:sales@statproxies.com">
  Email us to enable proxy exchange for your organization.
</Card>