Status lifecycle

The kit exposes its current state through taxKitStatus on useTaxKit(). Every status object has the same shape:

interface TaxKitStatusInfo {
  status: TaxKitStatusValue;
  title: string;
  description: string;
  actionLabel: string | null;
}

title, description, and actionLabel are pre-rendered for you — use them to drive partner-side UI like a status card or CTA button. The raw status value is one of the constants below.

Status values

The TaxKitStatus constants are exported from the package:

import { TaxKitStatus } from '@cointracker/tax-kit';

if (taxKitStatus?.status === TaxKitStatus.Synced) {
  // …
}

GetStarted'GET_STARTED'

Initial state — the user needs to connect their wallets/exchanges and start auto-sync. This is what new users see.

SyncingWalletsAndCalculatingCostBasis'SYNCING_WALLETS_AND_CALCULATING_COST_BASIS'

CoinTracker is pulling transaction history from connected accounts and computing cost basis. Long-running — can take minutes to hours depending on connection depth.

ReadyToImport'READY_TO_IMPORT'

Cost basis is calculated and tax lots are ready to send to the partner. Awaiting user confirmation on the review screen.

TransactionsNeedReview'TRANSACTIONS_NEED_REVIEW'

Some transactions require manual review before proceeding (e.g. unrecognized swap, missing cost basis). The kit surfaces a review queue.

ImportingCostBasis'IMPORTING_COST_BASIS'

Tax lots are being sent to the partner. Brief — completes within seconds in most cases.

Synced'SYNCED'

Tax lots successfully synced to the partner. The user can download their tax form via getTaxFormUrl().

UnableToSyncToPartner'UNABLE_TO_SYNC_TO_PARTNER'

The cost-basis import to the partner failed. Usually transient — the kit will surface a retry path.

UpgradePlanNeeded'UPGRADE_PLAN_NEEDED'

The user has reached their plan limit and needs to upgrade their CoinTracker subscription. The kit surfaces an upgrade CTA.

CostBasisFailed'COST_BASIS_FAILED'

Cost-basis calculation failed. Usually a data issue — the kit surfaces a contact-support path.

FixApiConnections'FIX_API_CONNECTIONS'

One or more connected wallets/exchanges have broken API credentials. The kit surfaces the reconnect flow.

Error'ERROR'

Generic error state — authentication failed, network issue, or unexpected backend response. Check useTaxKit().errors for specifics.

Typical happy-path sequence

For a new user, the status progresses linearly through the dark green states below. The orange states are off-happy-path branches the iframe can land in based on user data.

Loading diagram…

Returning users typically land in SYNCED directly, or in TRANSACTIONS_NEED_REVIEW / FIX_API_CONNECTIONS if their state has drifted since the last visit.

Mapping status to partner UI

A typical partner shell surfaces some of these states above the iframe (badges, banners, entry-point CTAs). Here's a starting point:

Status	Suggested partner-side UI
GET_STARTED	"Get started" CTA on tax-center entry. No badges.
SYNCING_WALLETS_AND_CALCULATING_COST_BASIS	"Calculating…" badge on tax-center entry. Don't block other navigation.
READY_TO_IMPORT	"Review and import" CTA with mild emphasis (e.g. dot indicator).
TRANSACTIONS_NEED_REVIEW	"Action needed" badge. Surface in nav until resolved.
IMPORTING_COST_BASIS	Spinner. Brief — usually resolves in seconds.
SYNCED	Default state. Show "Last synced: <timestamp>" using lastSyncUpdatedTimestamp.
UPGRADE_PLAN_NEEDED	Upgrade banner inside the iframe handles itself; you can mirror externally.
FIX_API_CONNECTIONS	"Action needed" badge. The iframe surfaces the reconnect flow.
COST_BASIS_FAILED / UNABLE_TO_SYNC_TO_PARTNER	Error badge. Encourage users to retry or contact support.
ERROR	Inspect useTaxKit().errors for the specific code; see Errors.

Driving partner UI

The pre-rendered fields on taxKitStatusInfo let you build a minimal status card without switching on the raw status:

function StatusCard() {
  const { taxKitStatus, open } = useTaxKit();
  if (!taxKitStatus) return <Spinner />;

  return (
    <Card>
      <h2>{taxKitStatus.title}</h2>
      <p>{taxKitStatus.description}</p>
      {taxKitStatus.actionLabel && (
        <button onClick={open}>{taxKitStatus.actionLabel}</button>
      )}
    </Card>
  );
}

When you do need to branch on a specific status (e.g. to hide the upgrade CTA for free-tier-only partners), use the TaxKitStatus constants — they're the only stable contract. The pre-rendered copy strings are not guaranteed to be byte-stable across SDK versions.