---
title: "Update the VAT number"
url: https://docs.corefinity.com/api/reference/billing/update-billing-vat-number
type: endpoint
last_updated: 2026-11-13
feature: billing
related:
  - https://docs.corefinity.com/guides/billing/billing-overview.md
---
# Update the VAT number

Saves or clears (`vat_number: null`) the billing account's VAT number, which changes the VAT on invoices
issued from now on, and answers the account's VAT basis as it now stands. Send the account's `version` as you
last read it: when the details were changed since, the save is refused `409 stale` and nothing is written. A
European Union number is saved as `pending` and checked afterwards.

```http
PUT /api/corestack/billing/account/vat-number
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 30 a minute
- Try it in the console: off. It has not been cleared for the console. Copy the request and run it yourself when you are sure.

## Query parameters

- `account` (integer): The billing account to read, by its `id` (see `GET /corestack/billing/account`). Left out, the request acts on your company's default billing account. An account that does not exist and one that is not your company's answer the same 404.
- `account_id` (integer): The same as `account`, under the name the MCP tools use. Send one of the two: when they name different accounts the request is refused `422 invalid` on `account_id`.

## Body

- `vat_number` (string or null): The VAT number; `null` clears it. Spaces, dots and hyphens are taken out and letters are made upper case before it is judged, so the 255 characters are only what the field takes as sent. What is left may hold letters, digits, `+` and `*`. For an account in a European Union country, a number that starts with neither a European Union country's prefix nor `GB` is given the account's (`EL` for Greece): `123456789` on a German account is saved as `DE123456789`; one that already starts with such a prefix is saved as sent. The number as it is saved, prefix included, is at most 20 characters. On a United Kingdom account it must have the United Kingdom's shape: `GB` and nine or twelve digits, or `GBGD` or `GBHA` and three digits.
- `version` (integer, required): The account's `version` as you last read it.

## Request

### curl

```bash
curl -X PUT https://manage.corefinity.com/api/corestack/billing/account/vat-number \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "vat_number": "GB123456789",
    "version": 1184934486
  }'
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->put('https://manage.corefinity.com/api/corestack/billing/account/vat-number', [
        'vat_number' => 'GB123456789',
        'version' => 1184934486,
    ]);

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/billing/account/vat-number', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    vat_number: 'GB123456789',
    version: 1184934486,
  }),
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.put(
    "https://manage.corefinity.com/api/corestack/billing/account/vat-number",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "vat_number": "GB123456789",
        "version": 1184934486,
    },
)

data = res.json() if res.content else None
```

## Responses

### 200 The account's VAT basis after the save.

```json
{
  "vat": {
    "buyer": null,
    "check": null,
    "country": "GB",
    "kind": "standard",
    "label": "UK VAT 20 %",
    "rate_percent": 20,
    "validation": {
      "state": "valid",
      "validated_at": null
    }
  }
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the `write` scope (`scope_required`), your company requires two-factor authentication and you have not set it up (`two_factor_required`), or you may not change your company's billing details (`billing_forbidden`).

```json
{
  "code": "billing_forbidden",
  "message": "Billing is available to your company's owner and billing contacts.",
  "reason": "billing_forbidden"
}
```

### 404 The id does not exist or is something you cannot see, or the feature is not on for your company (`feature_off`).

```json
{
  "code": "feature_off",
  "message": "Not found.",
  "reason": "feature_off"
}
```

### 409 The billing details were changed since you read `version` (`stale`). Read the account again and send its new `version`.

```json
{
  "code": "stale",
  "message": "Someone else changed these details. Reload and try again",
  "reason": "stale"
}
```

### 422 A field is missing or wrong (`invalid`); `field` names it. `version` is needed. A `vat_number` is refused for characters a VAT number cannot have, for being longer than 20 characters once it is tidied and given its country prefix, and, for a United Kingdom account, for a number that is not the United Kingdom's shape. An account with no billing country takes no VAT number (`field` is `country`): choose the country in the Control Panel first. `account` and `account_id` naming different billing accounts is refused on `account_id`.

```json
{
  "code": "invalid",
  "errors": {
    "account_id": [
      "Send account or account_id, not both: they name different billing accounts."
    ]
  },
  "field": "account_id",
  "message": "Send account or account_id, not both: they name different billing accounts.",
  "reason": "invalid"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `billing_forbidden` | Billing is for the organisation's owner and billing contacts. Ask one of them to do this. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 | `feature_off` | This feature is not on for your organisation yet. |
| 409 | `stale` | What you read has changed since you read it. Read it again, then send the change with its new version or quote. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |

## The same task elsewhere

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