Pricing and balance

A CartaFlow account has a prepaid balance in Brazilian reais (BRL). Every letter and every address verification is paid from that balance. The plan’s monthly fee is billed separately and does not come out of the balance.

How the price is builtCopy Anchor Link

A letter’s price comes in price, line by line. Each line has a quantity, the unit price on the account’s plan and the line amount.

Lines always come in that order, and lines that would be zero are left out. total is the sum of the lines and is the amount debited from the balance. Every amount is an integer in centavos (1/100 of a real): 1135 is R$ 11.35.

"price": {
  "currency": "BRL",
  "total": 1135,
  "items": [
    { "type": "base", "quantity": 1, "unit_amount": 990, "amount": 990 },
    { "type": "additional_sheets", "quantity": 1, "unit_amount": 75, "amount": 75 },
    { "type": "color", "quantity": 2, "unit_amount": 35, "amount": 70 }
  ]
}

• The destination does not change the price. It is the same for any postal code in Brazil.
• An address verification with the CartaFlow letter template costs the same as one base mailing on your plan: a single base line. With your own PDF, it is charged like a letter with the same options (additional sheets and color), with no Correios services. See Physical address verification.
• Double-sided printing is cheaper for multi-page documents, because it uses fewer sheets. Color is still charged per page. See Document and address area.

Correios servicesCopy Anchor Link

A letter goes as a simple letter ("carta simples") unless you choose optional Correios services in postal_services. Each service adds one line to the price:

"price": {
  "currency": "BRL",
  "total": 3340,
  "items": [
    { "type": "base", "quantity": 1, "unit_amount": 990, "amount": 990 },
    { "type": "registered", "quantity": 1, "unit_amount": 1175, "amount": 1175 },
    { "type": "return_receipt", "quantity": 1, "unit_amount": 1175, "amount": 1175 }
  ]
}

An address verification is always a simple letter. How each service works is in Letters and statuses.

Calculate the price before sendingCopy Anchor Link

POST /v1/letters/quote takes exactly the same body as POST /v1/letters, as JSON or with the PDF uploaded as a file. The API validates everything, completes the address from the postal code, counts the pages of the document and returns the price on the account’s current plan, including the Correios services you chose. Nothing is created or charged, and the balance does not need to cover the amount.

curl -X POST "https://api.cartaflow.com.br/v1/letters/quote" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "name": "Destinatário Exemplo", "postal_code": "01001-000", "number": "128", "complement": "Ap. 52" },
    "document": { "type": "url", "url": "https://arquivos.exemplo.com.br/faturas/2026-10-0042.pdf" },
    "color": true
  }'

The response has the plan used (plan), the pages (pages), the sheets (sheets), the complete address (to) and the price (price). If the dry run passes, creating the letter with the same body passes too, as long as there is balance.

When the balance is chargedCopy Anchor Link

When you cancel a letter or a verification that was already charged, the amount goes back to the balance right away. A scheduled letter canceled before its date was never charged, so there is nothing to refund. A verification canceled after production started is revoked (revoked), and the amount does not go back. See Cancel or revoke.

When a letter fails in production (status failed), the amount goes back to the balance automatically. Problems found before the charge, such as a PDF that breaks the rules, are never charged: the API answers 422 and nothing is created.

Check the balanceCopy Anchor Link

GET /v1/balance returns how much you can spend right now.

{
  "object": "balance",
  "currency": "BRL",
  "available": 48865,
  "pending": 0
}

• available is the amount available for new mailings, in centavos.
• pending is reserved for top-ups that depend on a payment being confirmed. Today balance is added at once, so pending is always 0.

Check the balance before large sends. You add balance in the dashboard, under Saldo e extrato > Adicionar saldo (Balance and statement > Add balance), and it is available at once. The CartaFlow team can also add balance to your account.

Reconcile spendingCopy Anchor Link

GET /v1/balance/transactions lists every movement in and out of the balance, newest first. Each transaction has the amount (amount, negative when it takes from the balance), the balance right after it (balance_after) and, when there is one, the id of the letter or verification behind it (source_id).

To close the month, filter by type and period: GET /v1/balance/transactions?type=letter&created_after=2026-10-01T00:00:00Z&created_before=2026-11-01T00:00:00Z. Use each letter’s reference and metadata to tie the cost to your customer or cost center. See Pagination and filters.