> ## 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.

# GET /v1/meta/pricing — Message Rate

> Published Meta / WhatsApp per-message rate by market, currency and category.

The published **Meta / WhatsApp Business Platform** per-message rate for a single market + currency + category — the list price Meta charges per delivered message. This is Meta's public rate card exposed as reference data; it is **not** your account's real billing.

## Endpoint

`GET https://pilotstatus.com.br/v1/meta/pricing`

<Note>
  Requires any valid API key (`ps_*`) in the `x-api-key` header. Both number-scoped and tenant-scoped keys work — pricing is global reference data, not tied to a number.
</Note>

## Query parameters

<ParamField query="market" type="string">
  Market code: ISO 3166-1 alpha-2 for countries (`BR`, `GB`, `IN`…), `NAM` for North America, or a region bucket (`AFR`, `APAC`, `CEEU`, `LATAM`, `MDE`, `WEU`, `GLO`).
</ParamField>

<ParamField query="currency" type="string">
  ISO 4217 currency code (`USD`, `BRL`, `EUR`, `GBP`, `INR`…).
</ParamField>

<ParamField query="category" type="string">
  `marketing`, `utility`, `authentication`, `service` or `authentication_international`. Required together with `market` and `currency`.
</ParamField>

<ParamField query="tiers" type="boolean">
  `true` / `1` → also return `volumeTiers` (Meta charges a lower price per message as monthly volume grows).
</ParamField>

## Modes

| Call                                  | Returns                                                                        |
| ------------------------------------- | ------------------------------------------------------------------------------ |
| No `market` / `currency` / `category` | **Metadata** — the available markets (code + name), currencies and categories. |
| `market` + `currency` + `category`    | The **flat price** for that combination.                                       |
| Anything partial                      | `400 MARKET_CURRENCY_CATEGORY_REQUIRED`.                                       |

## Examples

<CodeGroup>
  ```bash Price theme={null}
  curl "https://pilotstatus.com.br/v1/meta/pricing?market=BR&currency=BRL&category=authentication" \
    -H "x-api-key: ps_your_key_here"
  ```

  ```bash With volume tiers theme={null}
  curl "https://pilotstatus.com.br/v1/meta/pricing?market=BR&currency=BRL&category=authentication&tiers=1" \
    -H "x-api-key: ps_your_key_here"
  ```

  ```bash Metadata theme={null}
  curl "https://pilotstatus.com.br/v1/meta/pricing" \
    -H "x-api-key: ps_your_key_here"
  ```
</CodeGroup>

```json Price (200) theme={null}
{
  "market": "BR",
  "marketName": "Brazil",
  "currency": "BRL",
  "category": "authentication",
  "pricePerMessage": 0.035
}
```

```json With volume tiers (200) theme={null}
{
  "market": "BR",
  "marketName": "Brazil",
  "currency": "BRL",
  "category": "authentication",
  "pricePerMessage": 0.035,
  "volumeTiers": [
    { "from": 0,        "to": 500000,  "pricePerMessage": 0.035 },
    { "from": 500001,   "to": 3000000, "pricePerMessage": 0.0333 },
    { "from": 20000001, "to": null,    "pricePerMessage": 0.0263 }
  ]
}
```

```json Metadata (200) theme={null}
{
  "markets": [
    { "code": "BR", "name": "Brazil" },
    { "code": "NAM", "name": "North America" }
  ],
  "currencies": ["AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD","USD"],
  "categories": ["marketing","utility","authentication","service","authentication_international"],
  "source": "whatsappbusiness.com"
}
```

## Response fields

<ResponseField name="market" type="string">Market code echoed back.</ResponseField>
<ResponseField name="marketName" type="string">Human-readable market name.</ResponseField>
<ResponseField name="currency" type="string">ISO 4217 currency echoed back.</ResponseField>
<ResponseField name="category" type="string">The requested category.</ResponseField>

<ResponseField name="pricePerMessage" type="number">
  List price per delivered message in the requested currency. `0` for free categories (Service).
</ResponseField>

<ResponseField name="volumeTiers" type="array">
  Only when `tiers=1`. Each `{ from, to, pricePerMessage }` — the price drops as monthly volume grows; `to` is `null` on the unbounded top tier. Empty for categories without volume tiering (Marketing / Service).
</ResponseField>

## Message categories

| Category                       | What it covers                                                       |
| ------------------------------ | -------------------------------------------------------------------- |
| `marketing`                    | Promotions, offers, product suggestions, re-engagement.              |
| `utility`                      | Transactional / user-triggered updates (order, payment, delivery).   |
| `authentication`               | One-time passwords and identity verification.                        |
| `authentication_international` | Authentication to certain international destinations (its own rate). |
| `service`                      | Replies within the 24h customer service window — **free** (`0`).     |

<Note>
  Meta only changes prices on the 1st day of each quarter (≈1 month notice), so this rate card is refreshed on a schedule. Treat the values as indicative and confirm against Meta's official rate cards for exact billing.
</Note>

## Common errors

* `400 MARKET_CURRENCY_CATEGORY_REQUIRED` — provide `market`, `currency` and `category` together (or none, for metadata).
* `400 INVALID_CATEGORY` — the `category` value is not one of the five valid categories.
* `401` — missing or invalid `x-api-key` header.
* `404 PRICE_NOT_FOUND` — no published rate for that market + currency + category.