Account API

AccountErrorCode

export type AccountErrorCode = typeof ACCOUNT_ERROR_CODES[number];

AccountApiErrorBody

export type AccountApiErrorBody = {
    error: {
        code: AccountErrorCode;
        message: string;
    };
};

AccountAdmission

--- shapes -------------------------------------------------------------

export type AccountAdmission = "admitted" | "waitlisted";

AccountTenantView

export type AccountTenantView = {
    tenantId: TenantId;
    label: string;
    createdAt: number;
};

AccountView

GET /v1/account

export type AccountView = {
    subject: string;
    email: string;
    admission: AccountAdmission;
    tenant: AccountTenantView | null;
};

AccountTenantCreateRequest

POST /v1/account/tenant (header Idempotency-Key) → 201

export type AccountTenantCreateRequest = {
    label: string;
};

AccountTenantCreateResponse

export type AccountTenantCreateResponse = {
    tenantId: TenantId;
};

AccountKeyView

GET /v1/account/keys

export type AccountKeyView = {
    keyId: string;
    label: string;
    scopes: Scope[];
    createdAt: number;
    expiresAt: number | null;
    lastFour: string;
};

AccountKeysResponse

export type AccountKeysResponse = {
    keys: AccountKeyView[];
};

AccountKeyCreateRequest

POST /v1/account/keys → 201. The plaintext key appears only here, once.

export type AccountKeyCreateRequest = {
    label: string;
    scopes: Scope[];
    ttlDays?: number;
};

AccountKeyCreateResponse

export type AccountKeyCreateResponse = {
    keyId: string;
    apiKey: ApiKey;
};

AccountKeyRevokeResponse

POST /v1/account/keys/:keyId/revoke → 200

export type AccountKeyRevokeResponse = {
    keyId: string;
    revokedAt: number;
};

AccountHabitatsResponse

GET /v1/account/habitats

export type AccountHabitatsResponse = {
    habitats: HabitatView[];
    next?: string;
};

AccountCreditCheckoutRequest

POST /v1/account/credits/checkout

export type AccountCreditCheckoutRequest = {
    amountMicrocents: number;
};

AccountCreditCheckoutResponse

export type AccountCreditCheckoutResponse = {
    checkoutUrl: string;
};

AccountUsageResponse

GET /v1/account/usage

export type AccountUsageResponse = {
    balanceMicrocents: number;
    periodSpendMicrocents: number;
};

AccountOrgResponse

GET /v1/account/org — the account's org slug, or `org: null`.

export type AccountOrgResponse = {
    org: AccountOrgView | null;
};

AccountOrgView

export type AccountOrgView = {
    slug: string;
    createdAt: number;
};

AccountOrgRequest

POST /v1/account/org; PATCH /v1/account/org (rename while unbound).

export type AccountOrgRequest = {
    slug: string;
};

EndpointState

Endpoint lifecycle: live serves paid calls; paused refuses them; retired is terminal — a retired name can never be re-created or reactivated.

export type EndpointState = "live" | "paused" | "retired";

AccountEndpointView

GET /v1/account/endpoints item.

export type AccountEndpointView = {
    org: string;
    project: string;
    habitatId: string;
    mailbox: string;
    priceMicrocents: number;
    packSize: number;
    state: EndpointState;
    createdAt: number;
    updatedAt: number;
};

AccountEndpointCreateRequest

POST /v1/account/endpoints → 201.

export type AccountEndpointCreateRequest = {
    project: string;
    habitatId: string;
    mailbox: string;
    priceMicrocents: number;
    packSize: number;
};

AccountEndpointPatchRequest

PATCH /v1/account/endpoints/:project — omitted fields are unchanged. `state` may be "live", "paused" or "retired"; retired is terminal.

export type AccountEndpointPatchRequest = {
    priceMicrocents?: number;
    packSize?: number;
    state?: EndpointState;
};

AccountEndpointsResponse

GET /v1/account/endpoints

export type AccountEndpointsResponse = {
    endpoints: AccountEndpointView[];
    next?: string;
};

AccountEarningsEntry

GET /v1/account/earnings — the owner's journaled ledger view (W3-PAY). `availableMicrocents` is what apply/payout may draw: accrued − applied − paidOut − clawedBack.

export type AccountEarningsEntry = {
    seq: number;
    kind: string;
    microcents: number;
    ref: string;
    at: number;
};

AccountEarningsResponse

export type AccountEarningsResponse = {
    accruedMicrocents: number;
    appliedMicrocents: number;
    paidOutMicrocents: number;
    clawedBackMicrocents: number;
    availableMicrocents: number;
    connect?: {
        accountId: string;
        chargesEnabled: boolean;
        payoutsEnabled: boolean;
    };
    entries: AccountEarningsEntry[];
    next?: number;
};

AccountEarningsApplyRequest

POST /v1/account/earnings/apply — move available earnings into the spendable broker balance. Idempotent on the Idempotency-Key header.

export type AccountEarningsApplyRequest = {
    amountMicrocents: number;
};

AccountEarningsApplyResponse

export type AccountEarningsApplyResponse = {
    appliedMicrocents: number;
    balanceMicrocents?: number;
    duplicate?: boolean;
};

AccountPayoutLinkResponse

POST /v1/account/payouts/link — Connect Express onboarding URL for the account's bound (or newly created) Stripe account.

export type AccountPayoutLinkResponse = {
    url: string;
    accountId: string;
};

AccountPayoutRequest

POST /v1/account/payouts — transfer available earnings to the bound Connect account. `amountMicrocents` omitted pays the full available balance (floored to whole cents). Idempotent on Idempotency-Key.

export type AccountPayoutRequest = {
    amountMicrocents?: number;
};

AccountPayoutResponse

export type AccountPayoutResponse = {
    paidOutMicrocents: number;
    transferId?: string;
    duplicate?: boolean;
};