Account

Everything your integration needs to know about the account behind a key: which plan it is on, how much quota is left, how many VAT numbers it is monitoring, and whether the subscription is healthy.

Free to call: this endpoint spends no quota, never contacts VIES, and accepts both live and test keys. Safe to poll on a schedule or on every connection.

Endpoint

GET /v1/account

Terminal

curl https://api.vatnode.dev/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Paid Account

200 OK

{
  "key": {
    "id": "657668ba-d629-4401-b6d8-98627d15ec99",
    "label": "Production",
    "environment": "live"
  },
  "plan": {
    "id": "pro",
    "name": "Pro",
    "monthlyQuota": 10000,
    "subscriptionsLimit": 250,
    "webhooksLimit": 10
  },
  "usage": {
    "used": 10,
    "limit": 10000,
    "remaining": 9990,
    "overage": 0,
    "resetAt": "2026-09-14T00:00:00.000Z"
  },
  "monitoring": {
    "subscriptions": { "used": 0, "limit": 250 },
    "webhooks": { "used": 0, "limit": 10 }
  },
  "billing": {
    "status": "active",
    "interval": "month",
    "currentPeriodEnd": "2026-09-14T00:00:00.000Z",
    "nextChargeAt": "2026-09-14T00:00:00.000Z"
  }
}

Free Account

A free account has no subscription, so every field under billing is null. Monitoring is not part of the plan, which shows up as a limit of 0 rather than a missing section.

200 OK

{
  "key": {
    "id": "205718ba-774f-4d9e-8d1d-436569455841",
    "label": "Default",
    "environment": "live"
  },
  "plan": {
    "id": "free",
    "name": "Free",
    "monthlyQuota": 100,
    "subscriptionsLimit": 0,
    "webhooksLimit": 0
  },
  "usage": {
    "used": 0,
    "limit": 100,
    "remaining": 100,
    "overage": 0,
    "resetAt": "2026-08-25T00:00:00.000Z"
  },
  "monitoring": {
    "subscriptions": { "used": 0, "limit": 0 },
    "webhooks": { "used": 0, "limit": 0 }
  },
  "billing": {
    "status": null,
    "interval": null,
    "currentPeriodEnd": null,
    "nextChargeAt": null
  }
}

Fields

Field	Meaning
key	The key the request authenticated with: its id, the label you gave it in the dashboard, and whether it is `live` or `test`.
plan	Plan id, display name and its three limits. `-1` means unlimited, `0` means the feature is not part of the plan.
usage	Validations spent in the current quota window, the included limit, what is left, and when the window rolls over. `remaining` is floored at 0 and is `-1` on an unlimited plan.
usage.overage	Validations beyond the included quota in this window. Checks keep working past the limit where the plan allows overage — quota is not a hard stop.
monitoring	Monitored VAT numbers and registered webhooks against the plan limits, counted the same way the limits are enforced when you create one. A cancelled subscription or a deleted webhook frees its slot.
billing	Subscription state (`active`, `past_due`, `canceling`, `canceled`, or `null` on free), the cadence, and the end of the paid period.
billing.nextChargeAt	When the subscription renews. `null` unless the status is `active` — a cancelling subscription runs to the end of the period and is not charged again.

The Quota Window

The window is anchored to the day of the month you signed up, not to the first of the month. Sign up on the 25th and every window ends on the 25th. resetAt always reflects the current window, including for an account that has been idle long enough for the previous one to lapse.

Checking a Key

Because a revoked or malformed key returns 401, this endpoint doubles as a credential check — it is what the Zapier and Make integrations call when you connect an account. It costs nothing to call, so use it instead of validating a throwaway VAT number.

Privacy

An API key identifies an account, not a person. The response carries no email address, no name and no billing address — only entitlements and consumption.

Deciding before you call: read usage.remaining and monitoring.subscriptions to know whether a bulk job fits in the quota, or whether adding another monitored VAT number will be refused, before you send the request that gets rejected.