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

# Swap Number

> Get a replacement number for an active order if the original isn't receiving SMS.

`POST /api/v1/customer/swap/{orderId}`

Replace the phone number on an active order with a different one for the same service / country combination. The original number is released and a new one is allocated. The original price stands: no double-charge.

```bash theme={null}
curl -X POST https://virtualsms.io/api/v1/customer/swap/ORDER_ID \
  -H "x-api-key: YOUR_API_KEY"
```

## When to swap

* Original number isn't receiving SMS within a reasonable window
* Service flagged the original number as already-used (rare for our physical SIMs but possible)
* You need a different country code mid-flow (no: country can't change. Cancel and place a new order instead)

## 2-minute hold

Swaps are blocked for the first 2 minutes after purchase to prevent abuse. Inside that window the response is:

```json theme={null}
{ "error": "Swap not allowed within 2 minute hold period", "seconds_remaining": 87 }
```

## Response

```json theme={null}
{
  "success": true,
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "phone_number": "+447911999888",
  "previous_number": "+447911123456",
  "service": "tg",
  "country": "GB",
  "status": "pending",
  "expires_at": "2026-04-29T12:35:00Z"
}
```

## Notes

* `order_id` stays the same: only the number changes
* `expires_at` is reset to the original duration from the swap moment
* If no replacement is available, you'll get a 404 with `{"error":"No replacement available"}`. In that case use `/customer/cancel/{orderId}` for a refund.