# Meta costs

> What WhatsApp costs: estimated vs official, the Costs screen, currency conversion, spend cap and GET /v1/usage/costs.

Messajo shows what Meta charges for your messages and can pause campaigns when the month's spend reaches the cap you set. The values in the examples on this page are illustrative.

## What Meta charges

- Only WhatsApp is billed. Instagram and Messenger are not included.
- Billing is per **delivered** message, by category (marketing, utility, authentication, service) and recipient country. `sent` is not billed.
- `free_*` and `paid_exempt` messages are left out.
- The invoice is in the currency of the WhatsApp account.

## Estimated vs official

- **Estimated**: recorded on delivery. The price comes, in this order, from your own account's real cost for the same market and category over the last 30 days (volume discount included), from the price table downloaded from Meta, or from the table shipped in the repository. The source is stored on each message (`calibrated`, `rate_card` or `seed`).
- **Official**: the **approximate** value Meta reports per day. Messajo fetches it every day at 06:00 UTC, for the last 3 days. Days are in UTC.
- The difference comes from volume discounts and rounding. The panel warns when it exceeds 10% on a day.

## Costs screen

In **Costs** you pick the period and the connection and see the cards, the daily chart and the breakdown tabs. Campaign and template figures are always **estimated**. "No estimate" appears when the recipient has no phone number, the currency has no rate card or the category is not in the table.

## Currency conversion

Conversion uses the ECB rate of the day of each expense. `FX_PROVIDER=none` turns it off. A currency the ECB does not quote is not converted.

## Spend cap

- In **Settings → Costs** an owner or admin sets a monthly amount per currency, the warning percentages and whether campaigns pause at 100%.
- The month follows the organization's time zone.
- With pausing on, running campaigns pause with reason `spend_cap`. One-off and service sends continue.
- Starting or resuming returns `409` [`spend_cap_reached`](/en/errors#spend_cap_reached) until the month rolls over or you raise the cap. Resuming is manual.

## Through the API

`GET /v1/usage/costs` requires the `read` permission. Parameters: `from`, `to`, `connection_id`, `currency` and `group_by`.

```bash
curl -H "Authorization: Bearer $MESSAJO_API_KEY" \
  "https://api.messajo.com/v1/usage/costs?from=2026-11-10&to=2026-11-11&currency=BRL&group_by=day"
```

```json
{
  "currency": "BRL",
  "items": [
    { "key": "2026-11-10", "estimate": "37.5", "official": "36.92" },
    { "key": "2026-11-11", "estimate": "12.25", "official": null }
  ]
}
```

`message.status` carries the `cost` field:

```json
{
  "type": "message.status",
  "data": {
    "status": "delivered",
    "pricing": { "billable": true, "pricing_model": "PMP", "category": "marketing", "type": "regular" },
    "cost": { "estimate": "0.35", "currency": "BRL", "rate_card_version": "2026-10" }
  }
}
```

`cost` appears only on the status that triggered the charge (`delivered`, or `read` if `delivered` never arrived) and is `null` otherwise. `estimate: null` means charged, with no estimate.
