Skip to main content
POST /api/v1/customer/swap/{orderId} Swap replaces the number on an order with a fresh one for the same service and country, at no extra cost. Use it when a number is not receiving the SMS.
Swap instead of cancel-and-rebuy. Cancelling and purchasing again charges you a second time. Swapping does not — it carries the original charge across and records a zero-amount swap_free transaction. An agent that does not know this pays twice for one verification.

​
The order id changes

The old order is cancelled and a new order row is created. The response gives you both ids — poll for the SMS on new_order_id from here on.
price is what you already paid, echoed back — it is not charged again.

​
Rules

  • 120-second cooldown. A swap is refused for the first 120 seconds. Because the swap creates a new order, each swap starts its own fresh 120-second clock — the next swap is available 120 seconds after the previous one, not 120 seconds after the original purchase.
  • No cap. Beyond the cooldown there is no limit on how many times you may swap.
  • Only before the first SMS. Once an SMS arrives the order leaves waiting status and swap is refused.
  • Service and country are fixed. They are carried over from the original order and cannot be changed. To change either, cancel and place a new order.

​
Errors

Error bodies carry an error string only. There is no seconds_remaining field — parse the wait out of the message, or simply retry after 120 seconds.

​
If nothing is available

If no replacement number can be allocated, the swap fails and your original order is untouched. Use cancel for a full refund instead — or do nothing, and the order auto-expires and refunds after 20 minutes.