---
title: "Usage, limits, and plan"
method: GET
path: "/v1/billing"
tags: ["Billing"]
---

# Usage, limits, and plan

`GET /v1/billing`

## Request

- Base URL: `https://api.volanea.com`
- URL: `https://api.volanea.com/v1/billing`
- Auth: HTTP bearer

Current-month usage, the monthly caps, the plan and its per-cycle email quota, computed reputation, and subscription state in one call.

## Response `200`

The billing overview.

- Billing
  - `month` string, required: Current period, "YYYY-MM".
  - `used` integer, required: Non-test emails sent this month.
  - `limit` integer, nullable: Overall monthly send cap; `null` = unlimited.
  - `categories` object: Per-category usage and cap — transactional/campaign/workflow/inbound. Checked alongside (not instead of) the overall `limit`.
    - `transactional` BillingCategoryUsage
      - `limit` integer, nullable, required: `null` = unlimited.
      - `used` integer, required: Non-test sends this month in this category.
    - `campaign` BillingCategoryUsage
      - `limit` integer, nullable, required: `null` = unlimited.
      - `used` integer, required: Non-test sends this month in this category.
    - `workflow` BillingCategoryUsage
      - `limit` integer, nullable, required: `null` = unlimited.
      - `used` integer, required: Non-test sends this month in this category.
    - `inbound` BillingCategoryUsage
      - `limit` integer, nullable, required: `null` = unlimited.
      - `used` integer, required: Non-test sends this month in this category.
  - `plan` 'free' | 'starter' | 'growth' | 'scale' | 'enterprise', required
  - `emailQuota` integer, nullable, required: Email credits per monthly cycle for the current plan. Hard cap — sending stops when it's used up. `null` = unlimited (an enterprise contract with no monthly cap).
  - `contract` object, nullable: The enterprise contract managed by Volanea for this project, if any. While `phase` is `active` or `grace` it sets the quota instead of the plan.
    - `phase` 'active' | 'grace' | 'expired' | 'ended'
    - `termMonths` 3 | 6 | 9 | 12
    - `startsAt` string, date-time
    - `endsAt` string, date-time
    - `graceEndsAt` string, date-time
    - `daysRemaining` integer: Whole days until `endsAt`; negative once past.
    - `unlimited` boolean
    - `emailQuota` integer, nullable
    - `dailyLimit` integer, nullable
    - `renewals` integer
    - `note` string, nullable
  - `freeTierCredits` integer
  - `creditsUsed` integer, required: Credits used this cycle (1/email, 2 with attachments).
  - `planQuotas` object: Per-cycle quota of every self-serve plan — what an upgrade would buy.
    - `free` integer
    - `starter` integer
    - `growth` integer
    - `scale` integer
  - `reputation` object: Computed deliverability metrics. The worst of three windows (24h/7d/all-time) wins; `windows` breaks each one down. New projects (<30 days old) enforce at a lower volume floor.
  - `reputationState` 'ok' | 'warn' | 'throttled' | 'paused', required
  - `reputationReason` string, nullable
  - `dodo` object: Merchant-of-record provider (Dodo Payments) backing paid subscriptions. Disabled on self-host installs.
    - `enabled` boolean
    - `env` 'test_mode' | 'live_mode'
  - `dodoSubscription` object
    - `id` string, nullable
    - `status` 'active' | 'ended' | 'null', nullable
    - `plan` 'starter' | 'growth' | 'scale' | 'null', nullable
    - `cancelAtNextBillingDate` boolean
    - `nextBillingAt` string, date-time, nullable

## Other responses

- `401`: Missing or invalid API key.

---

[API](https://skmtc.dev/volanea/apis/volanea-api.md) · [All operations](https://skmtc.dev/volanea/apis/volanea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volanea/apis/volanea-api/revisions/9e187ae84fda?raw)