Billing & quotas

Plan, consumption, availability and plan changes.

Fetches require billing.view; changes require billing.manage. All operations use full_access.

GET/v1/billing/plan200 OK

full_access

Fetches the current plan and its consumption.

curl "$BASE_URL/billing/plan" -H "X-API-Key: $CORVO_API_KEY"

Response — 200 OK

{
  "data": {
    "plan": {
      "slug": "developer",
      "name": "Developer",
      "monthly_allowance": 250,
      "daily_limit": null,
      "max_active_companies": 999999,
      "monthly_price_cents": 2990
    },
    "usage": {
      "overage_units": 0,
      "overage_amount_cents": 0,
      "hard_limit": null,
      "credits_used": 10,
      "credits_reserved": 2,
      "credits_remaining": 238,
      "monthly_allowance": 250,
      "daily_usage": 3,
      "daily_limit": null,
      "active_companies": 1,
      "max_active_companies": 999999,
      "period_start": "2026-10-01T00:00:00.000Z",
      "period_end": "2026-10-31T23:59:59.000Z"
    },
    "subscription": {
      "status": "active",
      "paid_until": "2026-10-31T23:59:59.000Z",
      "cancel_at_period_end": false,
      "scheduled_plan": null,
      "blocked": false
    }
  }
}

Values are illustrative. This route uses snake_case, unlike billing/usage. If no plan is found after resolution: 404.

GET/v1/billing/usage200 OK

full_access

Fetches quota availability for issuance.

curl "$BASE_URL/billing/usage" -H "X-API-Key: $CORVO_API_KEY"

Response — 200 OK

{
  "data": {
    "canEmit": true,
    "creditsRemaining": 188,
    "creditsUsed": 10,
    "creditsReserved": 2,
    "monthlyAllowance": 200,
    "dailyUsage": 3,
    "dailyLimit": null,
    "activeCompanies": 1,
    "maxActiveCompanies": 10,
    "periodStart": "2026-10-01T00:00:00.000Z",
    "periodEnd": "2026-10-31T23:59:59.000Z"
  }
}

QuotaStatus: canEmit (boolean), reason?, creditsRemaining, creditsUsed, creditsReserved, monthlyAllowance, dailyUsage, dailyLimit (number or null), activeCompanies, maxActiveCompanies, periodStart, periodEnd (dates or null). Defined reason values: no_credits, daily_limit_exceeded, company_limit_exceeded, plan_blocked. The current check derives canEmit from credits, the daily limit and plan activity — it is not a guarantee that a company's fiscal data/certificate is ready. Quota fetches can initialize the default plan and refresh an expired period.

POST/v1/billing/upgrade200 OK

dashboard

Schedules the switch to the target plan on the subscription.

Field	Type	Required	Description
plan_slug	string	✓	Slug of the target plan, e.g. `"growth"`.

curl -X POST "$BASE_URL/billing/upgrade" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_slug": "growth" }'

Response — 200 OK

{
  "data": {
    "scheduled_plan": "growth",
    "effective_at": "2026-11-01T00:00:00.000Z"
  }
}

Dashboard-only route: API keys have no access (403). Requires an active subscription (409 otherwise) and returns scheduled_plan and effective_at; checkout and the billing portal also live in the dashboard.

POST/v1/billing/downgrade200 OK

dashboard

Schedules a plan change for the end of the period.

Field	Type	Required	Description
plan_slug	string	✓	Slug of the target plan, e.g. `"developer"`.

curl -X POST "$BASE_URL/billing/downgrade" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_slug": "developer" }'

Response — 200 OK

{
  "data": {
    "scheduled_plan": "developer",
    "effective_at": "2026-11-01T00:00:00.000Z"
  }
}

Public plan catalog

These three routes need no API key or session: use them to show prices on your own site or to size a plan. Amounts are in cents (...Cents) and the only cycle is monthly; any other cycle returns 400.

GET/v1/plans200 OK

public

Lists the plans with their monthly price and allowance.

Field	Type	Description
cycle	string	Only `monthly` is accepted (default).
limit	integer	Defaults to `50`; integer from 1 to 1000.
cursor	string	`nextCursor` from the previous page.

curl "$BASE_URL/plans"

Response — 200 OK

{
  "data": [
    {
      "slug": "developer",
      "name": "Developer",
      "monthlyAllowance": 250,
      "basePriceCents": 2990,
      "perCreditOverageCents": 12,
      "monthlyTotalCents": 2990,
      "currency": "BRL"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

Ordered from the smallest to the largest allowance. monthlyAllowance is the number of included credits, perCreditOverageCents the price of each credit above it and monthlyTotalCents the monthly price. This is the pricing view; GET /v1/credits/plans returns the plan limits and features instead.

GET/v1/plans/:slug200 OK

public

Fetches the price of one plan.

Field	Type	Required	Description
cycle	string		Only `monthly` is accepted (default).

curl "$BASE_URL/plans/growth"

Response — 200 OK

{
  "data": {
    "slug": "growth",
    "name": "Growth",
    "monthlyAllowance": 750,
    "basePriceCents": 8990,
    "perCreditOverageCents": 12,
    "monthlyTotalCents": 8990,
    "currency": "BRL"
  }
}

slug is free, developer, growth, scale or volume. An unknown plan returns 404.

GET/v1/plans/quote200 OK

public

Recommends the plan for a monthly volume of invoices and estimates the total cost.

Field	Type	Required	Description
volume	integer		Invoices per month. Required for a quote.
cycle	string		Only `monthly` is accepted (default).

curl "$BASE_URL/plans/quote?volume=20000"

Response — 200 OK

{
  "data": {
    "volume": 20000,
    "recommended_plan": "volume",
    "plan_name": "Volume",
    "monthly_allowance": 10000,
    "overage_credits": 10000,
    "overage_cost_cents": 90000,
    "base_price_cents": 89990,
    "total_estimated_cents": 179990,
    "currency": "BRL",
    "billing_cycle": "monthly"
  }
}

This route uses snake_case. total_estimated_cents is the plan price plus the estimated overage (overage_credits × the plan's price per credit). A missing, zero, negative or non-numeric volume returns 200 with { "data": null }, not an error.