---
title: "corestack_billing_vat_number_set"
url: https://docs.corefinity.com/mcp/tools/corestack_billing_vat_number_set
type: tool
last_updated: 2026-11-13
feature: billing
related:
  - https://docs.corefinity.com/guides/billing/billing-overview.md
---
# corestack_billing_vat_number_set

**Set the VAT number.** Set — or clear — your company's VAT number on its billing account (the `write` scope). An EU number is checked with VIES in the background; read corestack_billing_account_get for its state. Send the account's `version` as read. Scope: write.

- Scope: `write`
- Runs as a task: no

## When to use it

Set — or clear — your company's VAT number on its billing account. Ordering from the EU is for VAT-registered businesses: with a VAT number the EU reverse charge applies and no VAT is added to the invoices. The number is checked with the EU's VIES service in the background; nothing waits for it and nothing is refused for it. Read corestack_billing_account_get for the number's state (`pending` while VIES has not answered, then `valid` or `invalid`) and for the account's `version`, which this write sends back.

The same acceptance rule as the Control Panel's Billing details page: spaces, dots and dashes are removed, and an EU number with no country prefix gains its billing country's (`EL` for Greece, so `123456789` for a Greek account is stored `EL123456789`). It needs the `write` scope.

## Inputs

- `vat_number` (string or null): the VAT number, or null to clear it.
- `version` (integer, ≥ 0, required): the account's `version` as corestack_billing_account_get returned it. A stale one is refused with `stale`; read the account again and send the new version.
- `account_id` (integer, ≥ 1): one of your company's billing accounts; omitted, the company's default account.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "account_id": {
      "description": "One of your company's billing accounts (corestack_billing_account_get gives its id); omitted, the company's default account.",
      "minimum": 1,
      "type": "integer"
    },
    "vat_number": {
      "description": "The VAT number, or null to clear it. Spaces, dots and dashes are removed; an EU number with no country prefix gains its billing country's.",
      "type": [
        "string",
        "null"
      ]
    },
    "version": {
      "description": "The account's `version` as corestack_billing_account_get returned it; a stale one is refused with `stale`.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "version"
  ],
  "type": "object"
}
```

## Refusals

- `invalid_arguments` with `vat_number`: characters outside letters, numbers, `+` and `*`; more than 20 characters; or, for a GB number, not the GB shape (`GB123456789`, `GB123456789012`, `GD123`, `HA123`). Send a corrected number.
- `invalid_arguments` with `version`: missing, or not a non-negative integer.
- `stale`: someone changed the account's details (staff included) after you read them; read corestack_billing_account_get again and send its `version`.
- `billing_forbidden`: the person has no billing role in the company; ask a company owner or billing member.
- `tenant_mismatch`: the account is not one of your company's.
- `pin_refused`: the token is pinned to certain sites or clusters. The VAT number is the company's billing details on every order and invoice, so no site or cluster pin can cover setting it; the card offers a step-up to a token with no pins.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

A number VIES does not recognise is **not** a refusal: it is stored and the account's VAT check goes to staff, who contact the customer before the first invoice.

## Example

```json
{
  "name": "corestack_billing_vat_number_set",
  "arguments": {
    "vat_number": "DE123456789",
    "version": 384729103
  }
}
```

The answer carries the account's `vat` block:

```json
{
  "vat": {
    "country": "DE",
    "buyer": "business",
    "kind": "reverse_charge",
    "rate_percent": 0,
    "validation": {"state": "pending", "validated_at": null}
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_billing_vat_number_set with vat_number DE123456789, version 384729103. (Set the VAT number.) Tell me what it returned.
```

## The same task elsewhere

- Guide: [Billing](https://docs.corefinity.com/guides/billing/billing-overview.md)
