# Availability & pricing

Read which countries and number types Zernio sells, what each costs per month, and which capabilities each supports, from GET /v1/phone-numbers/countries.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

By the end of this page, you can:

- drive a country picker from `GET /v1/phone-numbers/countries`
- check one country's live stock and address rule with `GET /v1/phone-numbers/availability`
- know what a number costs before you buy it

## Before you start

You need an API key and usage-based billing, which telephony requires.

## Check availability (live)

Numbers are available in <NumberCountryCount /> countries. Each has a monthly price and one or more number types, each with its own price and capabilities.

The endpoint is the live source of truth. The tables below are a snapshot.

Call `GET /v1/phone-numbers/countries`. It returns every offerable country, cheapest first, with its current monthly price and a flag per capability.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: offer } = await zernio.phonenumbers.listPhoneNumberCountries();
for (const c of offer.countries) {
  console.log(c.code, `$${(c.monthlyCents / 100).toFixed(2)}/mo`, {
    calls: c.callsAvailable,
    sms: c.smsAvailable,
    whatsapp: c.whatsappAvailable,
    kyc: c.needsKyc,
    inStock: c.inStock,
  });
}
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

offer = client.phone_numbers.list_phone_number_countries()
for c in offer["countries"]:
    print(c["code"], f"${c['monthlyCents'] / 100:.2f}/mo",
          {"calls": c["callsAvailable"], "sms": c["smsAvailable"],
           "whatsapp": c["whatsappAvailable"], "kyc": c["needsKyc"], "inStock": c["inStock"]})
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/phone-numbers/countries" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Response (`200`):

```json
{
  "countries": [
    {
      "code": "US",
      "tier": 1,
      "monthlyCents": 300,
      "needsKyc": false,
      "callsAvailable": true,
      "whatsappAvailable": true,
      "smsAvailable": true,
      "outboundCallingAvailable": false,
      "inStock": true,
      "types": [
        { "numberType": "local", "monthlyCents": 300, "needsKyc": false, "smsAvailable": true, "whatsappAvailable": true, "callsAvailable": true, "inStock": true },
        { "numberType": "toll_free", "monthlyCents": 300, "needsKyc": false, "smsAvailable": false, "whatsappAvailable": false, "callsAvailable": true, "inStock": true }
      ]
    }
  ]
}
```

The country-level fields mirror the first entry of `types`, the default type.

- `inStock` is a carrier-stock snapshot refreshed every 6 hours and on availability checks. The purchase re-checks.
- `preOrderable: true` on a type means it is out of stock, but you can still order it through the [KYC form](/platforms/phone-numbers/kyc#out-of-stock-pre-order-it).
- `fulfilment: "request"` marks the types the carrier stocks nowhere and only sources to order.
- `outboundCallingAvailable` is WhatsApp Business Calling outbound, not PSTN calls.

## Check one country

`GET /v1/phone-numbers/countries` answers for the whole catalog. `GET /v1/phone-numbers/availability` answers for one country, and adds the address rule the registrant has to satisfy.

It takes:

- `country`
- an optional `numberType` (`local`, `mobile`, `national` or `toll_free`)
- an optional `sms=true`, which narrows every answer to the SMS-capable pool

Call it before you put anyone through the [KYC form](/platforms/phone-numbers/kyc). Regulated review is asynchronous and takes 1 to 3 business days.

```bash
curl "https://zernio.com/api/v1/phone-numbers/availability?country=BR&numberType=local" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

Response (`200`):

```json
{
  "country": "BR",
  "numberType": "local",
  "available": true,
  "addressConstraint": "geo",
  "areas": ["11"],
  "areaOptions": [
    { "ndc": "11", "name": "Sao Paulo", "count": 42 },
    { "ndc": "21", "name": "Rio de Janeiro", "count": 8 }
  ]
}
```

`addressConstraint` takes one of three values:

- `geo`: the registered address must be in the area of the number.
- `country`: any in-country address is accepted.
- `none`: no address is needed at all.

**Geo with no stock.** An address in an area with nothing in stock turns the KYC submit into a [pre-order](/platforms/phone-numbers/kyc#out-of-stock-pre-order-it) for that area (2 to 4 weeks).

That works only when the carrier can source one there. Otherwise it is refused with a `409`.

When `available` is `false`, `preOrderable` says whether the number can still be [pre-ordered](/platforms/phone-numbers/kyc#out-of-stock-pre-order-it).

`areaOptions` is the live inventory by area code. Pass an `ndc` from it as `areaCode` on the [purchase](/platforms/phone-numbers/setup#step-2-purchase) or on the KYC submit to hold the order to that area.

### Every area, in one of three states

`areaAvailability` lists every geographic area code of the country's numbering plan. It uses Google libphonenumber geocoding, one row per city (Madrid covers 910 to 919).

It is refreshed every 6 hours from the carrier's own inventory counts. It is the same answer the dashboard picker and the public country pages show.

```json
{
  "areaAvailability": {
    "inStock": [
      { "ndc": "919", "ndcs": ["919", "915", "911", "910", "..."], "name": "Madrid", "count": 50 },
      { "ndc": "954", "ndcs": ["954", "955", "854", "855"], "name": "Seville", "aliases": ["Sevilla"], "count": 41 }
    ],
    "preOrder": [{ "ndc": "641", "ndcs": ["641"], "name": "Giessen" }],
    "outOfStock": [{ "ndc": "212", "ndcs": ["212"], "name": "New York City, NY", "listed": 0 }]
  }
}
```

- Every row carries `ndcs`, every area code of the city deepest first (`ndc` is the one an order is placed against), and `aliases` when the city answers to other names. France's five codes are regions (4 is Southeast France: Lyon and Marseille alike), not cities.
- `inStock`: numbers we can sell now (`count` is the carrier's count minus the numbers we hold back). Pass `ndc` as `areaCode` to hold the order to it. Equal to `areaOptions`.
- `preOrder`: the carrier lists nothing there and the type is a document tier. Submit KYC with `areaCode` and `preOrder: true`; the carrier sources one, usually in 2 to 4 weeks, and nothing is billed until it is active.
- `outOfStock`: nothing deliverable and no pre-order. `listed` above 0 is stock the carrier shows that WhatsApp refused recently (held back until it clears); 0 is a dry area of an instant tier. A [stock watch](#watch-an-out-of-stock-country) with `areaCode` is the way to hear when it is back.

Empty lists mean the pair has no cached coverage yet, not that the country has no areas.

`soldOutAreas` (pre-order plus out of stock, each with `preOrderable`) stays for older clients.

## Watch an out-of-stock country

`inStock: false` is not a dead end.

**Pre-order it.** If the type is `preOrderable`, order it now: submit the [KYC form](/platforms/phone-numbers/kyc#out-of-stock-pre-order-it). We get the number from stock the moment it returns, or sourced by the carrier, usually within 2 to 4 weeks.

**Watch it.** If you would rather wait, or the type cannot be pre-ordered, call `POST /v1/phone-numbers/stock-watches` with a `country` (and an optional `numberType`).

It puts you on the list for the moment that country has deliverable numbers again.

Add `areaCode` (with `numberType`) to watch one area. When that area can be bought today as a pre-order, the response says so with `preOrderable: true`. The watch is armed either way.

```bash
curl -X POST "https://zernio.com/api/v1/phone-numbers/stock-watches" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "country": "IE", "numberType": "local" }'
```

Response (`201`):

```json
{
  "id": "67b1c2d3e4f5a6b7c8d9e0f1",
  "country": "IE",
  "countryName": "Ireland",
  "numberType": "local",
  "createdAt": "2027-01-04T09:00:00Z"
}
```

Stock is re-checked every 6 hours. When it comes back, Zernio emails the account holder and sends [`phone_number.stock_available`](/webhooks/phone/phone-number-stock-available).

The watch is consumed when it fires, so create it again if you miss the stock.

One watch covers one country and number type. A repeat request returns the existing watch with a `200`.

A `409` means either:

- the country is in stock right now, so buy instead, or
- you already hold the maximum of 20 watches.

List them with `GET /v1/phone-numbers/stock-watches`. Cancel one with `DELETE /v1/phone-numbers/stock-watches/{id}`.

## Pricing by country

Price is per number, per month. It is charged in full at activation and on the 1st of each month (no daily proration).

It is separate from usage (call minutes, SMS segments). The [phone number price list](/pricing/phone#price-by-country) expands each country into its number types, with price, provisioning and SMS-capable stock per type.

Countries marked with a dagger provision instantly. Every other country returns `needsKyc: true` and requires a one-time [KYC form](/platforms/phone-numbers/kyc). The number then activates within 1 to 3 business days of the regulatory review.

<NumberPriceBands />

Countries under **Pre-order** hold no stock. Order a number with the [KYC form](/platforms/phone-numbers/kyc#out-of-stock-pre-order-it) and it is sourced for you, usually within 2 to 4 weeks.

Their prices are in the [price list](/pricing/phone#pre-order-numbers), marked Pre-order.

<RatesGeneratedAt />

Prices are computed server-side:

- 1.5x the carrier's monthly cost
- rounded up to a whole dollar
- $3 minimum and $30 at the top of the range

A country whose carrier cost is too high to price is not offered.

The endpoint above always returns the current price. Treat the bands as indicative.

## Number types

Numbers are `local`, `mobile`, `national` or `toll_free`, depending on the country's inventory.

Each country has a default type, chosen to work across capabilities. Where a country offers more than one, pick another at purchase with `numberType`.

Toll-free is not sold in every country.

<Callout type="warn">Toll-free can never connect WhatsApp. `numberType: "toll_free"` with the default `connectWhatsapp: true` returns a `400`, so buy it with `connectWhatsapp: false` and use it for calls and SMS.</Callout>

## Capabilities by country

| Capability | Where |
|---|---|
| Calls (PSTN) | Every country, on by default on every number. Receiving calls works from anywhere. Outbound calls, and forwarding a call to a phone number, reach only the destination countries enabled for calling, and some high-cost destinations are capped. A blocked destination fails the call or the forward: `POST /v1/voice/calls` returns a [`502`](/platforms/voice/outbound#if-it-fails), and a browser call is accepted, then marked `failed`. Ask support to review a destination you need. |
| SMS | Australia, Belgium, Canada, United Kingdom, Lithuania, Netherlands, Poland, Puerto Rico, Sweden, United States, U.S. Virgin Islands and South Africa. Even there, SMS is confirmed per number, not per country. |
| WhatsApp | Every country. Any number except toll-free can be connected to a WhatsApp Business Account. |
| WhatsApp outbound calling | Everywhere except the US, Canada, Egypt, Vietnam and Nigeria, where Meta blocks business-initiated calls (inbound still works). This is [WhatsApp Business Calling](/platforms/whatsapp/calling), a different feature from PSTN calls. |
| Branded Calling | US numbers only, for businesses registered in the US or Canada. Displays on calls to US mobiles on T-Mobile and Verizon; see [Branded Calling](/platforms/phone-numbers/branded-calling). |

<Callout type="warn">
SMS is a per-number capability. Search with `sms=true` and purchase with `wantsSms: true` to draw only from the SMS-capable pool.
</Callout>

`smsAvailable` says where SMS-capable stock exists. The real check happens when you [enable SMS](/platforms/sms/setup) on a specific number, and a number that cannot text is refused.

## If it fails

A `400` on `GET /v1/phone-numbers/available` or `POST /v1/phone-numbers/purchase` means the country is not offerable:

```json
{
  "error": "Country not available",
  "type": "invalid_request_error"
}
```

Pick a `code` from the countries response.

A `422` with `code: "USAGE_BILLING_REQUIRED"` on purchase means the team is not on usage-based billing.

Every error uses the envelope in [error handling](/guides/error-handling).

## Related

- [Buying a number](/platforms/phone-numbers/setup): search inventory and purchase.
- [Porting](/platforms/phone-numbers/porting): bring a number you already own.
- [Phone number price list](/pricing/phone#price-by-country): every country, expandable by number type.
- [List offerable countries](/phone-numbers/list-phone-number-countries): every field of the response.