# Number tiers

> Compare the Free, Standard and Pro tiers, see how a Number's 24-hour billing windows work, and change a Number's tier.

Each Number has a tier: Free, Standard or Pro. The tier sets the Number's
capabilities and limits, and what it costs for each 24-hour window it is
online. A project's default tier applies to its Numbers unless a Number has its
own.

## Compare tiers

| | Free | Standard | Pro |
| --- | ---: | ---: | ---: |
| Credits per 24-hour window | 0 | 25 | 36 |
| Throughput | 5 messages/s | 10 messages/s | 100 messages/s |
| Included data | 1 GB | 25 GB | 100 GB |
| Inbound calls per month | 5 | Unlimited | Unlimited |
| Outbound calls per month | 5 | 50 | Unlimited |
| Serverless invocations per month | 1,000 | 250,000 | 1,000,000 |
| Campaigns | No | No | Yes |
| BanSafe Lite: Safe Mode and warm-up plan | No | Yes | Yes |
| Ban Credit | No | No | Yes |

Numbers with the `+55` calling code use 85% of the listed rate. The discount
follows the Number's country code, not the payment currency. Every Number on a
tier uses the same rate, however many Numbers the team connects.

You can choose Free only for test numbers, and test numbers use no credits
whatever their tier. A Free team's one real Number runs on Standard at 0
credits. Real Numbers on Pay-As-You-Go use Standard or Pro. An Enterprise
agreement can set a negotiated Standard or Pro rate.

## How billing windows work

A paid window lasts 24 hours from a successful connection.

1. Pairing reserves the first window's credits before the pairing code
   appears. For a new pairing, the reservation covers the full rate.
2. When the connection succeeds, Polymorfa reads the Number's calling code,
   applies any regional discount, charges the window and releases the rest of
   the reservation.
3. When the window ends, the next window is charged if the Number is still
   running.

Reconnecting within paid time does not buy another window. **Stop** prevents
further windows but does not pause time already paid. A Number that cannot
fund its next window is suspended, with its pairing kept.

The Numbers table and the Number's details show **Paid time remaining**, which
counts down to the end of the paid window even while the Number is stopped or
disconnected. **Paid window expired** and **No paid window** mean what they
say.

Cloud API Numbers whose WhatsApp charges Meta bills to you directly do not buy
windows.

### Restart a stopped Number

A stopped Number needs a funded start to reconnect. A start is refused when
the team lacks credit, when credit is protected for higher-priority projects,
or when payments are on hold. A refused start buys no window and enables
nothing; the Number shows as disconnected. Check the billing notice, add
credits or adjust [budgets and priority](https://docs.polymorfa.com/billing/spending-budgets), then start
it again.

## Overages

Usage above a tier's allowance uses credits. It is never blocked.

| Usage | Applies to | Rate |
| --- | --- | ---: |
| WhatsApp data, including media and hosted message storage | Standard, Pro | 10 credits per GB-month |
| Outbound calls | Standard | 20 credits per call |
| Serverless invocations | Standard, Pro | 100 credits per million |

Allowances belong to each Number; unused allowances are not pooled across a
project. Free has no overage. See [Usage](https://docs.polymorfa.com/billing/usage) for what each Number
consumed.

## Change a Number's tier

**Console:**

1. Open the Number's settings and choose its tier.
2. Select **Review plan change** and check the credit charge and timing.
3. Confirm. The Console shows the result once it is applied.

Closing the preview without confirming changes nothing.

**API:**

1. Quote the change with
   [`POST /platform/sessions/{sessionId}/tier-quotes`](https://docs.polymorfa.com/api/numbers/quote-session-tier-change).
   A `null` `tierOverride` returns the Number to the project default. A quote
   changes nothing and lasts ten minutes, or until the Number or price changes.
2. Confirm the quote's `quoteId` with
   [`PATCH /platform/sessions/{sessionId}`](https://docs.polymorfa.com/api/numbers/set-session-tier-override).
3. Read [`GET /platform/sessions/{sessionId}/tier-quotes/{quoteId}`](https://docs.polymorfa.com/api/numbers/get-session-tier-change)
   until the result is `applied` or `rejected`. `queued` does not grant the
   tier.

```bash cURL
curl -X POST "https://api.polymorfa.com/platform/sessions/$SESSION_ID/tier-quotes" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tierOverride": "pro" }'

# After the customer accepts this exact quote:
curl -X PATCH "https://api.polymorfa.com/platform/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "'"$QUOTE_ID"'" }'

curl "https://api.polymorfa.com/platform/sessions/$SESSION_ID/tier-quotes/$QUOTE_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const quoted = await platform.sessions.quoteTierChange("<number-id>", {
  tierOverride: "pro",
});
const quote = quoted.data.data;
console.log(quote.quote.amountCents, quote.quote.effectiveAtMs);

// After the customer accepts this exact quote:
await platform.sessions.setTierOverride("<number-id>", { quoteId: quote.id });

const result = await platform.sessions.retrieveTierChange("<number-id>", quote.id);
console.log(result.data.data.status);
```

Show the quoted charge before you confirm it. `amountCents` is in credits and
can have up to six decimal places. Both calls need `sessions:manage`.

- **Upgrade**: buys a full new 24-hour window when applied. The rest of the old
  window is not refunded or carried over.
- **Downgrade**: the paid tier stays until its window ends and the new tier
  applies from the next window.
- **Not enough credit**: the Number keeps its current tier and window.

To change the default for a project's Numbers, edit **Default Number tier** in
the project's settings. See [Change project settings](https://docs.polymorfa.com/teams#change-project-settings).

## See also

- [How billing works](https://docs.polymorfa.com/billing)
- [Buy credits](https://docs.polymorfa.com/billing/credits)
- [Usage](https://docs.polymorfa.com/billing/usage)
- [List tier pricing](https://docs.polymorfa.com/api/billing/list-tier-pricing)
