# Change an Account

Its name, tags, visibility and users, and its `customerRefId` once.

## Overview

- Send at least one field; each follows the rules of [Create an Account](https://docs.aureahub.com/docs/account-create.md). `"name": null` clears the name; `tags` and `users` replace the whole list.
- `customerRefId` is set once: changing one that is set answers `409` `ACCOUNT_REF_IMMUTABLE` (`The account's customerRefId is set and never changes.`); sending the same value again changes nothing. One another account holds: `409` `ACCOUNT_REF_TAKEN`.
- **The owner does not change while the account holds wallets**: `409` `ACCOUNT_OWNER_HOLDS_WALLETS` (`The account holds wallets of its owner: its owner does not change.`). Viewers can always change.
- **A default account** (its id is a user's): its owner is its user — name the user as `owner`, or leave the user out, else `400` `ACCOUNT_DEFAULT_OWNER` (`A default account belongs to its user: name it as the owner, or leave it out.`). The first change stores it.
- `404` `ACCOUNT_NOT_FOUND`; `400` `ACCOUNT_USER_UNKNOWN`, `ACCOUNT_REQUEST_INVALID`. For `owner`, `tenantadmin` and `non_signing_admin`, on their own tenant. With `account.updated` to the endpoints that name it.

## Endpoint

### `PATCH /v1/accounts/{accountId}`

Authentication: bearer token required.

Changes an account's name, tags, visibility, users, or sets its customerRefId.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | string (uuid) | yes | The account's id; a user's id for that user's default account |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customerRefId` | string | no | Set once |
| `name` | string \| null | no | 1–100 characters; `null` clears it |
| `tags` | string[] | no | Replaces the tags |
| `hidden` | boolean | no | Left out of the default account lists; nothing else changes |
| `users` | object[] | no | Replaces the users: `[{ userId, access }]` |

**Responses**

`200` Changed

```json
{
  "id": "3b8f2c6e-1d4a-4e9b-8f7c-2a5d6e9b1c40",
  "customerRefId": "cust-00042",
  "name": "Savings, customer 42",
  "tags": ["retail", "eu", "vip"],
  "hidden": false,
  "isDefault": false,
  "frozen": false,
  "users": [
    { "userId": "5d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d", "access": "owner" },
    { "userId": "e4b1c7d9-2f6a-4c83-9b0e-5a7d3f1c8e26", "access": "viewer" }
  ],
  "wallets": [],
  "createdBy": "0d2f6b8a-4c1e-4a93-b7d5-2e9f1c3a8b60",
  "createdAt": "2026-10-07T09:12:40.511Z",
  "updatedAt": "2026-10-07T09:30:02.118Z"
}
```

`409` Reference set

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "The account's customerRefId is set and never changes.",
  "details": { "code": "ACCOUNT_REF_IMMUTABLE" }
}
```

**Example request**

```bash
curl -X PATCH https://api.aureahub.com/v1/accounts/3b8f2c6e-1d4a-4e9b-8f7c-2a5d6e9b1c40 \
  -H "Authorization: Bearer $TENANT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["retail", "eu", "vip"] }'
```

---

Web version: https://docs.aureahub.com/#account-update