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

# Extra Numbers & On Demand

> Buy extra WhatsApp numbers via /v1/subscription/extra-numbers — preview cost, Free → On Demand conversion, and payment via saved card or checkout URL.

# Extra numbers & On Demand

Buy an extra WhatsApp number via the public API with a **tenant-scoped** key. Pricing follows the **On Demand** model: you pay a **monthly price per connected number** (set per-tenant by the Pilot Status team) and get **unlimited messages** on every number.

<Note>
  Number-scoped keys get **403** — use the tenant-scoped key (dashboard **Profile → API**).
</Note>

## GET /v1/subscription/extra-numbers — Preview (dry-run)

```bash theme={null}
curl "https://pilotstatus.com.br/v1/subscription/extra-numbers?quantity=1" \
  -H "x-api-key: ps_your_tenant_scoped_key"
```

Returns the cost and whether buying converts the plan:

```json theme={null}
{
  "requiresConversion": true,
  "fromPlan": "FREE",
  "toPlan": "ON_DEMAND",
  "currentNumbers": 1,
  "requested": 1,
  "billedQuantity": 2,
  "unitPriceBRL": 29.9,
  "monthlyTotalBRL": 59.8,
  "messagesBecomeUnlimited": true,
  "hasSavedCard": false,
  "explanation": { "pt": "…", "en": "…" }
}
```

## POST /v1/subscription/extra-numbers — Buy

```bash theme={null}
curl -X POST "https://pilotstatus.com.br/v1/subscription/extra-numbers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -d '{ "quantity": 1, "confirm": true }'
```

Behaviour:

* **Free → On Demand conversion.** If you are on the **Free** plan, buying an extra number moves you to On Demand: your current (formerly free, 200-message-limited) number becomes a **paid, unlimited** number **and** the new number is billed too. So buying 1 extra while Free bills you for **2** numbers. Because this changes what you pay, the `POST` returns **409 `CONFIRMATION_REQUIRED`** (with the preview) unless you send `confirm: true`.
* **Already On Demand / paid.** Buying increments your number count; messages stay unlimited.
* **Payment.** If a card is saved (dashboard **Plans → Cartão**), it is charged immediately and the slot is unlocked. Otherwise the response is `{ "success": true, "charged": false, "checkoutUrl": "https://…" }` — open it to pay; once paid, the slot unlocks (webhook) and you can create the number with `POST /v1/numbers`.
* **Stripe only.** On Demand billing is card-based (no PIX).

<Note>
  Save a card first (so API purchases charge instantly) in the dashboard under **Plans → Cartão**.
</Note>

## POST /v1/billing/checkout — Wallet top-up / add a card

Generates a hosted checkout URL for billing actions:

```bash theme={null}
curl -X POST "https://pilotstatus.com.br/v1/billing/checkout" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -d '{ "purpose": "wallet_topup" }'
```

* `purpose: "wallet_topup"` — top up the prepaid wallet.
* `purpose: "add_card"` — save a card for future On Demand charges.

The response contains a `checkoutUrl` to open in the browser.