Orders

Purchase and manage virtual number orders via the API.

Order Lifecycle

Create Order

{
  "countryId": "clxxx...",
  "serviceId": "clxxx...",
  "quantity": 1
}

Response

{
  "success": true,
  "data": {
    "id": "clxxx...",
    "status": "ACTIVE",
    "phoneNumber": "+5511999999999",
    "sellPrice": 3.5,
    "expiresAt": "2026-07-05T15:30:00.000Z",
    "country": { "code": "BR", "name": "Brazil", "flag": "🇧🇷" },
    "service": { "slug": "whatsapp", "name": "WhatsApp" }
  }
}

Cancel / Finish

# Cancel an order that has not received an SMS — refunds in full
POST /api/v1/orders/{id}/cancel

# Finish after receiving SMS
POST /api/v1/orders/{id}/finish

Refunds

A number that never delivers a code is not a service rendered, so the full amount goes back to your wallet automatically:

• Cancelled without SMS — refunded when you call /cancel.
• Expired without SMS — refunded automatically when the number expires. No call needed.
• Provider failure — refunded, and the order is marked FAILED.

Once any SMS arrives the number counts as delivered and there is no refund. Cancelling such an order is rejected with 400 — close it with /finish instead. Every refund appears as a REFUND transaction in your wallet history.

Rate Limits

API keys allow 120 requests per minute, and order creation is capped at 20 per minute per account — the dashboard and the API share that budget. Exceeding a limit returns 429 carrying Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining, so you know exactly how long to back off.