> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Subscription status card

The main billing card for a customer account page. Includes plan, status, discount, scheduled changes, and action buttons.

---

## What it does

The headline card on a customer's billing or account page. Shows their current plan, price breakdown, status (active, trialing, past-due, paused, canceled), any active discount, and upcoming scheduled changes.

## When to use

- You're building your own billing screen rather than using the [customer portal](https://developer.paddle.com/concepts/customer-portal.md).
- You want a single component that surfaces everything a subscriber needs to know about their plan at a glance.
- You need to drive the customer toward a specific action using the `onChangePlan`, `onUpdatePaymentMethod`, and `onManageSubscription` callbacks.

Pair with [Subscription alert](https://developer.paddle.com/sdks/components/subscription-alert.md) above the card to surface state changes prominently before the customer scans the detail.

**Registry:** [`https://developer.paddle.com/r/subscription-status-card.json`](https://developer.paddle.com/r/subscription-status-card.json)

## Install

```bash
npx shadcn@latest add @paddle/subscription-status-card
```

Also runnable with `pnpm dlx shadcn@latest add @paddle/subscription-status-card` or `yarn dlx shadcn@latest add @paddle/subscription-status-card`.

## Props

- **subscription** (SubscriptionStatusData): Subscription data — items, totals, status, billing cycle, discount, scheduled changes. Pass undefined to render the skeleton loading state.
- **title** (string): Override the card title. Defaults to the first item's product name (single-item subscriptions) or "Subscription" (multi-item).
- **statusBadgePosition** ("inline" | "end"): Where the status badge sits. end is right-aligned; inline renders next to the plan name (useful for tighter layouts).. Default: `"end"`
- **onChangePlan** (() => void): Called when the user clicks Change plan. Only rendered when the subscription isn't paused or canceled — paused subs must be resumed first, canceled is a terminal state.
- **onUpdatePaymentMethod** (() => void): Called when the user clicks Update payment method. Only rendered for automatically-collected subscriptions that aren't paused or canceled.
- **onManageSubscription** (() => void): Called when the user clicks Manage. Always rendered when provided — the action is consumer-defined (portal link, modal, resubscribe flow, etc.).
- **className** (string): Extra Tailwind classes applied to the root element.