Skip to content

Ordering numbers

How an order works

The life of an order from purchase to code — every status, what moves it along, and exactly when you're refunded.

Last updated
Updated
Reading time
2 min read
On this page4
  1. The happy path
  2. When nothing arrives
  3. The 20-minute window
  4. After the order

Every one-time order moves through a small, predictable set of states. Each appears as a status pill in your console and as status in the API.

The happy path

Text
pending ──► waiting ──► received ──► completed
Status What it means What you can do
pending You've paid and we're assigning a number. This usually takes a moment. Wait a moment.
waiting The number is yours and listening for an SMS. A countdown shows the time left. Use the number, or cancel for a refund.
received At least one SMS has arrived and the code is shown. More messages can still arrive. Copy the code, then finish the order.
completed You finished the order, or its time ran out after a message arrived. Nothing — it's done.

When nothing arrives

Status What happened Refund
cancelled You cancelled while it was waiting, before any SMS arrived. Full, immediately
expired 20 minutes passed without an SMS. Full, automatic
failed We couldn't assign a number — for example, stock ran out a moment after you bought. Full, automatic

Every refund appears in your ledger as its own line, pointing at the order. An order is never charged twice and never refunded twice, however many times a request is retried.

The 20-minute window

A number stays assigned to your order for 20 minutes from the moment it's assigned. During that window:

  • Every SMS sent to the number is attached to your order, including resends.
  • The console shows the latest code, and the full text of every message is kept with the order.

When the window closes, a waiting order becomes expired and is refunded, and a received order becomes completed. You don't need to keep the page open: expiry and refunds happen on our side.

Tip

Need more than one code from the same service? Don't finish the order until you're completely through its sign-up flow. See Requesting another code.

After the order

Once an order is over, its number rests for a cooldown period, then goes back to the shared pool. It's never handed to anyone for the same service again. Can I reuse a number? explains what that means for you.