---
title: "GET /v1/billing"
method: GET
path: "/v1/billing"
---

# GET /v1/billing

`GET /v1/billing`

## Request

- The document declares no server URL.
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-better-auth.session_token`

The organisation's standing with the biller. Any member may read it; reachable while access is withdrawn.

## Response `200`

The request has succeeded.

- Billing: What the organisation is entitled to — the same answer the gates give: the biller's row, with any operator hold applied on top.
  - `entitlement` 'active' | 'past_due' | 'suspended', required: `active` · `past_due` · `suspended`. Only `suspended` withdraws access. `past_due` is a biller's "the payment failed" and is a warning the console renders, not a switch — a card that expired on a Tuesday should not read as a service that was turned off. Which failed payment becomes a suspension, and when, is a biller's policy: nothing in the service reads a clock. The Platform document carries the same vocabulary on the operator's `Entitlement`; this is the founder's read of it.
  - `hold` 'suspended' | 'comped', required: An operator's hold on the organisation — FounderMail's own act, beside the biller's. A hold wins outright: `suspended` withdraws access whatever the subscription says (ban beats billing), and `comped` provides `plan` with no subscription needed (a comp survives the biller). Lifting one puts the biller's last word back in force at once.
  - `plan` 'founder' | 'team', required: The two things for sale, ruled 2026-09-14: capacity is STORAGE, and everything countable — people, agents, mailboxes, addresses, domains — is unlimited on both. `founder` is $20 a month for 20 GB of mail; `team` is $200 for 200 GB. A dollar a gigabyte, in two sizes. Never a seat: a person's mailbox and an agent's cost the same, which is the product's whole premise.
  - `currentPeriodEnd` string, date-time, nullable, required: When the paid period ends — or, while `trialing`, when the trial ends. Advisory: no gate reads it, and in `past_due` it is the end of the UNPAID period, not a date access lasts until. Null until a biller has written it.
  - `standing` 'none' | 'customer' | 'trialing' | 'subscribed', required: The organisation's standing with the biller — which door `/billing` opens. `none`: no customer on file; checkout is the door. `customer`: a customer on file with no live subscription — a trial or a subscription that ended, or a checkout that was not finished; checkout is the door. `trialing`: the 14-day trial every new organisation starts on, with no card on file yet; "add a card" (the portal) is the door, and when the trial ends without one the biller cancels and access is withdrawn. `subscribed`: a subscription stands, or a trial with a card that will simply continue; the portal is the door, and checkout answers 409.
  - `deletion` Deletion, required
    - `scheduledFor` string, date-time, required: When it runs: seven days after it was asked for.
    - `started` boolean, required: It has begun, and can no longer be cancelled.
  - `capacityBytes` integer, nullable, required: What the plan includes, in bytes — `OrgStorage.bytes` is measured against it. Null exactly when `plan` is null. A fair-use line, not a gate: nothing refuses at it.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/foundermail/apis/org.md) - [All operations](https://skmtc.dev/foundermail/apis/org/llms.txt) - [OpenAPI document](https://skmtc.dev/foundermail/apis/org/revisions/8bbb36e378ab?raw)