---
title: "One organization's billing: subscription, invoices, Build Credits ledger, charges, usage"
method: GET
path: "/operator/billing/accounts/{organizationId}"
tags: ["Operator"]
---

# One organization's billing: subscription, invoices, Build Credits ledger, charges, usage

`GET /operator/billing/accounts/{organizationId}`

## Request

- Base URL: `https://hostingsurge.com/api/v1`
- URL: `https://hostingsurge.com/api/v1/operator/billing/accounts/{organizationId}`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-hs_session`

## Path parameters

- `organizationId` string, uuid, required

## Response `200`

Account

- object
  - `organizationId` string, uuid, required
  - `organizationName` string, required
  - `planId` 'free' | 'pro' | 'business', required
  - `subscriptionStatus` 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | 'paused' | 'null', nullable, required
  - `interval` 'month' | 'year' | 'null', nullable, required
  - `currentPeriodEnd` string, nullable, required: ISO-8601 timestamp
  - `cancelAtPeriodEnd` boolean, required
  - `trialEnd` string, nullable, required: ISO-8601 timestamp
  - `dunningState` 'ok' | 'past_due' | 'restricted', required
  - `pastDueSince` string, nullable, required: ISO-8601 timestamp
  - `graceUntil` string, nullable, required: ISO-8601 timestamp
  - `deploysBlockedAt` string, nullable, required: ISO-8601 timestamp
  - `customerId` string, nullable, required
  - `livemode` boolean, nullable, required
  - `mrr` integer, required: USD list price per month of the current subscription, also for one billed in a local currency (0 on Free or while trialing)
  - `openAmount` integer, required: amount remaining on open invoices
  - `invoices` object[], required
    - `id` string, required
    - `number` string, nullable, required
    - `status` 'draft' | 'open' | 'paid' | 'uncollectible' | 'void', required
    - `kind` 'subscription' | 'one_off' | 'build_credits' | 'other', required
    - `currency` string, required
    - `subtotal` integer, required: minor units (cents)
    - `tax` integer, nullable, required: minor units (cents)
    - `total` integer, required: minor units (cents)
    - `amountDue` integer, required: minor units (cents)
    - `amountPaid` integer, required: minor units (cents)
    - `amountRemaining` integer, required: minor units (cents)
    - `createdAt` string, required: ISO-8601 timestamp
    - `periodStart` string, nullable, required: ISO-8601 timestamp
    - `periodEnd` string, nullable, required: ISO-8601 timestamp
    - `dueDate` string, nullable, required: ISO-8601 timestamp
    - `paidAt` string, nullable, required: ISO-8601 timestamp
    - `hostedInvoiceUrl` string, nullable, required
    - `pdfUrl` string, nullable, required
    - `description` string, nullable, required
  - `creditLedger` object[], required
    - `id` string, uuid, required
    - `kind` 'grant' | 'debit' | 'reversal', required
    - `source` string, required
    - `credits` number, required
    - `reference` string, required
    - `note` string, nullable, required
    - `createdAt` string, required: ISO-8601 timestamp
  - `charges` object[], required
    - `id` string, uuid, required
    - `reference` string, required
    - `kind` string, required
    - `amount` integer, required: minor units (cents)
    - `currency` string, required
    - `description` string, required
    - `status` 'pending' | 'invoiced' | 'paid' | 'scheduled' | 'failed' | 'canceled' | 'refunded', required
    - `invoiceId` string, nullable, required
    - `createdAt` string, required: ISO-8601 timestamp
  - `usage` object, nullable, required
    - `organizationId` string, uuid, required
    - `planId` 'free' | 'pro' | 'business', required
    - `period` object, required
      - `start` string, required: ISO-8601 timestamp
      - `end` string, required: ISO-8601 timestamp
      - `source` 'subscription' | 'calendar_month', required
    - `metrics` object[], required
      - `metric` 'projects' | 'databases' | 'seats' | 'buildMinutes' | 'bandwidthGb' | 'storageGb' | 'aiCredits' | 'emailsPerDay' | 'emailsPerMonth', required
      - `unit` 'count' | 'minutes' | 'gb' | 'credits', required
      - `label` string, required
      - `measured` boolean, required: false: no data source yet ("not metered yet"); used is then null
      - `used` number, nullable, required
      - `limit` number, nullable, required: included amount or allowance; null = unlimited
      - `cap` number, nullable, required: hard cap the team set (build minutes); null = none
      - `enforcedAt` 'create' | 'deploy' | 'builder' | 'send' | 'none', required: send: transactional email, refused with rate_limited once the quota is used (emailsPerDay resets 00:00 UTC, emailsPerMonth with the period)
      - `percent` number, nullable, required: used / limit in percent (rounded), null when unlimited or unmeasured
      - `state` 'ok' | 'warning' | 'reached' | 'over', required: warning ≥ 80%, reached ≥ 100%, over: beyond the included amount and billed
      - `overage` object, nullable, required
        - `quantity` number, required
        - `unitAmountDecimal` string, required
        - `currency` string, required
        - `estimatedAmount` integer, required: minor units (cents)
    - `credits` object, required
      - `renewal` 'monthly' | 'once', required
      - `allowance` number, required: credits included by the plan (per period, or once on Free)
      - `allowanceUsed` number, required
      - `allowanceRemaining` number, required
      - `purchased` number, required: remaining purchased or granted credits; they never expire. Negative = a debt from a refunded or disputed top-up that was already spent, repaid by the next purchase
      - `remaining` number, required: allowanceRemaining + purchased (a negative purchased balance counts as 0: a debt never reduces the allowance)
      - `usedThisPeriod` number, required
    - `alerts` object[], required: 80%/100% warnings raised in the current period
      - `metric` 'projects' | 'databases' | 'seats' | 'buildMinutes' | 'bandwidthGb' | 'storageGb' | 'aiCredits' | 'emailsPerDay' | 'emailsPerMonth', required
      - `threshold` union, required
        - 80
        - 100
      - `createdAt` string, required: ISO-8601 timestamp

## Other responses

- `400`: Invalid request (code invalid_request)
- `401`: Missing or invalid session/token (code unauthorized)
- `403`: Authenticated but not permitted (code forbidden); details.requiresSession for plan/payment changes over a token
- `404`: Not found or not visible to the caller (code not_found)
- `409`: Conflicting state, e.g. a subscription already exists (code conflict)
- `429`: Too many requests (code rate_limited); see Retry-After
- `501`: Billing is not set up on this server (code not_configured)
- `503`: The payment provider is unavailable (code provider_unavailable)

---

[API](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api.md) · [All operations](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/revisions/4d08337cdff1?raw)