# Custos da Meta

> Quanto o WhatsApp custa: estimado × oficial, tela de Custos, conversão de moeda, teto de gasto e GET /v1/usage/costs.

O Messajo mostra quanto a Meta cobra pelas suas mensagens e pode pausar campanhas quando o gasto do mês chega ao teto que você definir. Os valores dos exemplos desta página são ilustrativos.

## O que a Meta cobra

- Só o WhatsApp tem cobrança. Instagram e Messenger não entram.
- A cobrança é por mensagem **entregue**, por categoria (marketing, utilidade, autenticação, serviço) e país do destinatário. `sent` não cobra.
- Mensagens `free_*` e `paid_exempt` não entram na conta.
- A fatura sai na moeda da conta do WhatsApp.

## Estimado × oficial

- **Estimado**: gravado na entrega. O preço sai, nesta ordem, do custo real da sua conta no mesmo mercado e categoria nos últimos 30 dias (já com desconto por volume), da tabela de preços baixada da Meta ou da tabela que vem no repositório. A origem fica gravada em cada mensagem (`calibrated`, `rate_card` ou `seed`).
- **Oficial**: valor **aproximado** que a Meta informa por dia. O Messajo busca todo dia às 06:00 UTC, dos últimos 3 dias. Os dias são em UTC.
- A diferença vem de desconto por volume e de arredondamento. O painel avisa quando ela passa de 10% num dia.

## Tela de Custos

Em **Custos** você escolhe o período e a conexão e vê os cartões, o gráfico diário e as abas de recorte. Campanha e template são sempre **estimados**. Aparece "sem estimativa" quando o destinatário não tem telefone, a moeda não tem tabela ou a categoria está fora da tabela.

## Conversão de moeda

A conversão usa a cotação do BCE do dia de cada gasto. `FX_PROVIDER=none` desliga a conversão. Moeda que o BCE não cota não converte.

## Teto de gasto

- Em **Configurações → Custos** o dono ou admin define um valor mensal por moeda, os percentuais de aviso e se as campanhas pausam em 100%.
- O mês segue o fuso da organização.
- Com a pausa ligada, campanhas rodando pausam com motivo `spend_cap`. Envios avulsos e de serviço seguem.
- Iniciar ou retomar devolve `409` [`spend_cap_reached`](/errors#spend_cap_reached) até virar o mês ou subir o teto. A retomada é manual.

## Pela API

`GET /v1/usage/costs` exige a permissão `read`. Parâmetros: `from`, `to`, `connection_id`, `currency` e `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 }
  ]
}
```

O `message.status` traz o campo `cost`:

```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` vem só no status que gerou a cobrança (`delivered`, ou `read` se o `delivered` não chegou) e é `null` nos demais. `estimate: null` quer dizer cobrada, sem estimativa.
