---
title: "Subscription, billing state and effective plan of an organization"
method: GET
path: "/v1/organizations/{organization_id}/billing/subscription"
tags: ["Billing"]
---

# Subscription, billing state and effective plan of an organization

`GET /v1/organizations/{organization_id}/billing/subscription`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/organizations/{organization_id}/billing/subscription`
- Auth: HTTP bearer

Owner/billing members (browser) or any API key of the organization (read-only). `billing_state`: free (no paid subscription), active, canceling (ends at period end, then free limits), grace (payment overdue, workspaces unaffected), restricted (grace ended: new opens/resumes answer 402 entitlement_required).

## Path parameters

- `organization_id` string, uuid, required

## Response `200`

Default Response

- object
  - `organization_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `mode` union, required
    - 'test'
    - 'live'
  - `billing_state` union, required
    - 'free'
    - 'active'
    - 'canceling'
    - 'grace'
    - 'restricted'
  - `plan` object, nullable, required: The plan whose limits admission enforces now.
    - `plan_key` string, required
    - `catalog_version` string, required
    - `source` union, required
      - 'override'
      - 'subscription'
      - 'trial'
      - 'default'
    - `ends_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `subscription` object, nullable, required
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `status` string, required: Stripe status: incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid, paused.
    - `plan_key` string, nullable, required
    - `catalog_version` string, nullable, required
    - `current_period_start` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `current_period_end` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `cancel_at_period_end` boolean, required
    - `cancel_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `canceled_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `ended_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `past_due_since` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `grace_until` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `restricted` boolean, required
    - `restriction_reason` string, nullable, required
    - `entitlement_state` union, required
      - 'none'
      - 'active'
      - 'grace'
      - 'restricted'
    - `synced_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `restrictions` object, required
  - `pending_checkout` object, nullable, required
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `plan_key` string, nullable, required
    - `status` string, required
    - `expires_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `purchase_available` boolean, required: Checkout/portal are configured in this environment.
  - `custom_plan` object, nullable, required: A plan arranged with Shardflux for this organization (the one in force, else the next scheduled one).
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `name` string, required: Display name, e.g. "Scale (custom)".
    - `base_plan_key` string, required: The catalog plan it is built on.
    - `status` union, required: active: in force now; scheduled: starts at starts_at.
      - 'active'
      - 'scheduled'
    - `billing` 'manual_invoice', required: Invoiced by Shardflux directly; no card charge or Stripe subscription.
    - `price` object, required
      - `amount_minor` integer, required: Agreed price in minor units (cents).
      - `currency` string, required
      - `interval` union, required: one_off: once for the whole term.
        - 'one_off'
        - 'month'
        - 'year'
    - `starts_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `ends_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `overage` union, required: on: usage past the allowances keeps running and is invoiced with the plan; off: the allowances are caps.
      - 'on'
      - 'off'
    - `limits` object, required: Admission limits of the plan (null = unlimited).
    - `allowances` object, required: Allowances per month of the plan.

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

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