# updateTokenAccount

mutation · in the family [Token account](/reference/token-account/)

## What it does

Edit your group’s kernel wallet — the prepaid balance that pays for platform usage — change its details.

Edit a TokenAccount's mutable attributes. Requires the unrestricted capability + the record's CURRENT revision.

## Careful

Edits take effect immediately and write a new revision; the old revision stays in history.

## Who may call it

Capability area: **Billing and the wallet** — Your platform bill, token purchases and the usage and cost reads.

- Owner
- Manager
- Associate Manager
- An API key whose scope allows `api:updateTokenAccount`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | yes | The id of the record. |
| `revision` | [ID](/types/#scalars) `ID!` | yes | The revision id you read on the record; the change is refused if an edit landed in the meantime. |
| `input` | [EditTokenAccountInput](/types/EditTokenAccountInput/) `EditTokenAccountInput!` | yes | No further notes. |

## Returns

[TokenAccount](/types/TokenAccount/) `TokenAccount!` — A TokenAccount — \*\*the ONE-per-GROUP token wallet / platform billing unit\*\* (AT/stack billing of MERCHANTS; 1 org or 100 orgs share ONE pool — is the billing aggregation point; per-org figures are consumption ATTRIBUTION, reporting-only). The wallet is a GROUP-scoped SINGLETON enforced by the tokenAccountSingleton UNIQ marker minted IN the create txn. \*\*Wallet existence IS the metering arm\*\* (ruling): no wallet ⇒ the group is unbilled (the DVLP posture); opening one arms the rater (the slice-4 leg). balance = Σ TokenEntry amounts EXACTLY, cached in the SAME transaction as every ledger append — SIGNED (ruling: the ledger never lies; a transient sub-zero overshoot is honest state; exhaustion balance ≤ 0 fires the system:token_exhaustion CASCADE-suspend of member orgs, reload ≤0→>0 fires system:token_reload unsuspend-to-ACTIVE). The auto-top-off block is CONFIG this slice (the FIRING engine + stored-method custody = the rater leg, deferral 5); its budget cap is a LAZY month-keyed counter (ruling — rolls by key comparison, no scheduled reset). FSM: active(i) ⇄ inactive (paused — purchases/grants refuse REF_STATE; the rater still debits: usage happened) → doomed (gate-protected; the inbound-ref set is EMPTY by design — entries and purchases are FAMILY \[the GiftRegistry vacuous-gate class]). Platform billing is USD-only. NOT searchable (platform-internal — never merchant search content). Template class A16_BILLING (platform billing ≠ floor work — owner/manager/assoc_mgr; hand-derived v23).

## Example request

```graphql
mutation ExampleUpdateTokenAccount($id: ID!, $revision: ID!, $input: EditTokenAccountInput!) {
  updateTokenAccount(id: $id, revision: $revision, input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    balance
    lowBalanceThreshold
    dailyBurnThresholdKernels
    autoTopOffMonth
    autoTopOffSpentUsdCents
    autoTopOffDay
    autoTopOffSpentDayUsdCents
    autoTopOffPendingMethod
    autoTopOffPrimaryFailedDay
    autoTopOffBackupFailedDay
    burn7dKernels
    runwayDays
    microTokenCarry
    lowBalanceSince
    autoTopOffPendingPurchaseId
    topOffCappedSince
    baseFeePaidMonth
    includedMonth
    includedGranted
    includedRemaining
    affiliateCreditCents
    frozenKernels
    storageSnapshotDay
    currency
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "input": {
    "caption": "Blue jeans"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

## Example response

```json
{
  "data": {
    "updateTokenAccount": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TA-EXMP-0000-000F",
      "type": "TokenAccount",
      "caption": "Blue jeans",
      "status": "active",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "balance": 1,
      "lowBalanceThreshold": 1,
      "dailyBurnThresholdKernels": 1,
      "autoTopOffMonth": "<auto top off month>",
      "autoTopOffSpentUsdCents": 1,
      "autoTopOffDay": "2027-01-31",
      "autoTopOffSpentDayUsdCents": 1,
      "autoTopOffPendingMethod": "<auto top off pending method>",
      "autoTopOffPrimaryFailedDay": "2027-01-31",
      "autoTopOffBackupFailedDay": "2027-01-31",
      "burn7dKernels": 1,
      "runwayDays": 1.5,
      "microTokenCarry": 1,
      "lowBalanceSince": "<low balance since>",
      "autoTopOffPendingPurchaseId": "01900000-0000-7000-8000-80a20c5b0000",
      "topOffCappedSince": "<top off capped since>",
      "baseFeePaidMonth": "<base fee paid month>",
      "includedMonth": "<included month>",
      "includedGranted": 1,
      "includedRemaining": 1,
      "affiliateCreditCents": 1,
      "frozenKernels": 1,
      "storageSnapshotDay": "2027-01-31",
      "currency": "USD"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))
- `NOT_FOUND/*` — That record could not be found. ([NOT_FOUND](/errors/NOT_FOUND/))
- `CONFLICT/*` — The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. ([CONFLICT](/errors/CONFLICT/))
- `VALIDATION/VERSION_REQUIRED` — The request did not say which app version it came from. ([VALIDATION](/errors/VALIDATION/))

## Dry run

Add `dryRun: true` to the request envelope (`extensions.at`) to rehearse this call: every check runs, the write is rehearsed against the current records and nothing is stored; the answer is the refusal a real call would give, or the record it would create. Every response to a rehearsal carries `dryRun: true`, so a rehearsed record is never mistaken for a saved one.