---
title: "Get Subscription Status"
method: GET
path: "/api/billing/subscription/status"
tags: ["billing"]
---

# Get Subscription Status

`GET /api/billing/subscription/status`

## Request

- Base URL: `https://api.civilquants.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.civilquants.com/api/billing/subscription/status`
- Auth: none declared

Poll for Subscription-row landing after a successful Checkout.

The /welcome page hits this every ~1s up to ~10s after a Stripe
Checkout redirect. Returns `pending` until the
`customer.subscription.created` webhook lands and the row is linked
to the authenticated user (via `metadata.clerk_user_id` — set
server-side on the Checkout Session creation).

Auth: Clerk JWT only. API tokens / pass_holders are rejected — they
are not the buy-flow surface. The DB lookup filters on user_id so
one user cannot poll arbitrary subscription IDs to infer existence;
a row belonging to another user collapses to the same `pending`
response shape as a missing row.

## Query parameters

- `stripe_subscription_id` string, required

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- SubscriptionStatusResponse: Polling response for the /welcome page. `status="ready"` means the Subscription row exists in our DB for the authenticated user; the page can flip from "Confirming…" to the welcomed state. `status="pending"` means the webhook hasn't yet landed (or the row is orphaned, or the row belongs to another user — leakage-safe collapsing). The endpoint deliberately does NOT echo customer-email, Stripe customer-id, or any field that would let a poll-and-iterate attacker learn anything beyond "you own this subscription_id."
  - `status` 'ready' | 'pending', required
  - `tier` string, nullable
  - `subscription_status` string, nullable
  - `current_period_end` integer, nullable

## Other responses

- `422`: Validation Error

---

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