---
title: "Get the company's active Median subscription, with plan + payment method"
method: GET
path: "/companies/{companyId}/checkout/subscription"
tags: ["Checkout"]
---

# Get the company's active Median subscription, with plan + payment method

`GET /companies/{companyId}/checkout/subscription`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/companies/{companyId}/checkout/subscription`
- Auth: HTTP bearer

Returns the joined view of a company's Median (SaaS) subscription,
shaped for the Billing & Plan card in the customer app. When the
local median_subscriptions row is missing but the company already
has a Stripe customer, the service resyncs from Stripe before
returning (self-heals missed webhook deliveries).

## Response `200`

Subscription (null when the company has none)

- object
  - `success` true, required
  - `data` CheckoutSubscriptionResponse, required
    - `id` string, uuid, nullable, required
    - `companyId` string, uuid, required
    - `status` 'active' | 'past_due' | 'cancelled' | 'trialing' | 'incomplete' | 'needs_attention', required: Missing or ambiguous platform items project needs_attention; cancellation takes precedence.
    - `stripeSubscriptionStatus` string, nullable, required: Exact provider status from the last observation.
    - `platformItemState` 'unverified' | 'present' | 'missing' | 'ambiguous', required
    - `platformItemId` string, nullable, required
    - `providerObservedAt` string, date-time, nullable, required
    - `platformTermsVerifiedAt` string, date-time, nullable, required
    - `stripeSubscriptionId` string, nullable, required
    - `stripePriceId` string, nullable, required
    - `currentPeriodStart` string, date-time, nullable, required
    - `currentPeriodEnd` string, date-time, nullable, required
    - `cancelledAt` string, date-time, nullable, required
    - `planTier` string, nullable, required
    - `plan` CheckoutSubscriptionPlan, required
      - `id` string, uuid, required
      - `name` string, required
      - `priceCents` integer, required
      - `interval` 'month' | 'year', required
      - `features` string[], required
    - `billing` CheckoutSubscriptionBilling, required: What Stripe actually charges the subscription each period. Differs from the plan's list price whenever a coupon applies — a comped company has an effectiveAmountCents of 0 against a non-zero listAmountCents.
      - `listAmountCents` integer, required
      - `effectiveAmountCents` integer, required: The recurring charge each period once billing starts. While trialEndsAt is set this amount is not yet being charged.
      - `interval` 'month' | 'year', required
      - `discountLabel` string, nullable, required
      - `trialEndsAt` string, date-time, nullable, required: Date the trial ends and effectiveAmountCents starts being charged. Non-null means nothing is due until then, and clients must show both the zero due now and the recurring amount with this date.
      - `discountEndsAt` string, date-time, nullable, required: Date the coupon expires and listAmountCents resumes. Null when the coupon runs for the life of the subscription.
    - `paymentMethod` CheckoutSubscriptionPaymentMethod, required
      - `brand` string, required
      - `last4` string, required
      - `expMonth` integer, nullable, required
      - `expYear` integer, nullable, required
    - `paymentMethodStatus` 'available' | 'none' | 'unavailable' | 'not_configured', required: Whether Stripe returned a payment method, confirmed that none is configured, or could not establish the answer. The not_configured state means the company has no Stripe customer id; show "No Stripe billing on file" without a Stripe portal action. An unavailable result must not be presented as "No payment method". Neither state permits displaying the stored payment-method summary as current.
    - `paymentMethodSummary` string, nullable, required
    - `source` 'median_subscription' | 'stripe_resync' | 'billing_plan_fallback', required

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member

---

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