AlmondTill/G3N API

On this page

attachTokenAccountBillingMethod

mutation · in the family Billing and the wallet

What it does

Attach a payment method to your group’s kernel wallet — how top-ups get paid.

Attach ONE stored off-session payment method to the caller-group's wallet: the wallet's platform Stripe Customer mints LAZILY (idempotent — a retry converges on the SAME Customer), the method attaches, then ONE OCC write stamps the server-only refs + the readable {brand, last4, attachedAt} facts (the refs NEVER cross the wire — read billingMethod instead). A wallet already carrying a method refuses CONFLICT/REF_STATE (detach first; replacement is the explicit auditable two-step). ⚠ Custody ARMS the charger's auto-top-off + base-fee lanes (the merchant consents to off-session charges by storing the method). Requires the unrestricted capability. Template class A16_BILLING (hand-derived v24).

Careful

A real card on file for platform billing.

Who may call it

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

Arguments

NameTypeRequiredNotes
inputAttachTokenAccountBillingMethodInput AttachTokenAccountBillingMethodInput!yesNo further notes.

Returns

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

mutation ExampleAttachTokenAccountBillingMethod($input: AttachTokenAccountBillingMethodInput!) {
  attachTokenAccountBillingMethod(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:

{
  "input": {
    "methodRef": "<method ref>"
  }
}

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

Example response

{
  "data": {
    "attachTokenAccountBillingMethod": {
      "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

Used in