---
title: "Get the authenticated user subscription"
method: GET
path: "/api/v1/subscription"
tags: ["Subscription"]
---

# Get the authenticated user subscription

`GET /api/v1/subscription`

## Request

- Base URL: `https://www.poster.ly`
- URL: `https://www.poster.ly/api/v1/subscription`
- Auth: HTTP bearer

Return the authenticated user posterly subscription summary: status, tier, cancel-at-period-end, current period end, trial end, and pause state. Includes connected account usage and the account limit for the workspace the caller is acting in. Also returns what to do next for this user: `upgrade_options` (plans above theirs with prices, limits and credits), `next_steps` (respecting status; a plan upgrade is the `upgrade_subscription` step, and `billing_url` is the fallback when an upgrade cannot be made from here; the upgrade step id is `upgrade_plan`, formerly `change_plan`) and, for an Agency workspace owner, `extra_accounts`. Requires the `billing:read` scope. This endpoint bypasses the API add-on paywall so a user can always inspect and manage their own subscription. Returns 404 `no_subscription` when the user has no subscription.

## Response `200`

Subscription summary fetched successfully.

- SubscriptionSummaryResponse
  - `subscription` SubscriptionSummary, required
    - `id` string, nullable
    - `status` string, nullable: Subscription status, e.g. active, trialing, paused, canceled.
    - `tier` string, nullable: Plan tier, e.g. starter, pro, power_user, agency.
    - `cancel_at_period_end` boolean, nullable
    - `current_period_end` string, date-time, nullable
    - `trial_ends_at` string, date-time, nullable
    - `paused_at` string, date-time, nullable
    - `pause_resumes_at` string, date-time, nullable
    - `stripe_subscription_id` string, nullable
    - `accounts` object, nullable: Connected accounts for the workspace this caller is acting in. limit is the plan tier plus any extra slots. -1 means unlimited.
      - `workspace_id` string, nullable
      - `used` integer
      - `limit` integer
    - `upgrade_options` object[]: The plans above the caller's, with real prices, account limits and included credits. Empty on Agency, while paused, past due, canceled or cancel-pending, and for a teammate who is not the workspace owner.
      - `tier` 'starter' | 'pro' | 'power_user' | 'agency'
      - `name` string
      - `monthly_price` number: USD per month.
      - `yearly_price` number: USD per year.
      - `max_accounts` integer
      - `included_credits` integer: AI credits included per month (yearly plans receive them monthly).
    - `next_steps` object[]: What to do next for this user's tier and status. A plan upgrade is the upgrade_subscription tool (POST /api/v1/subscription/upgrade); billing_url stays the fallback for the cases it refuses (API and MCP add-on, a discount to handle first, no card subscription, an ineligible subscription). The upgrade step id is `upgrade_plan` (it was `change_plan` before upgrades existed: match on `tool` rather than the id).
      - `id` string, required
      - `text` string, required
      - `tool` string: The real MCP tool that performs this step, when one exists.
      - `params` object: Arguments to start with. Money tools still quote first.
    - `billing_url` string: The billing page, where plan changes are made.
    - `extra_accounts` ExtraAccountsState
      - `eligible` boolean, required: True when the owner can buy or remove extra accounts right now.
      - `code` string, nullable: Why not eligible: agency_required, no_stripe_subscription, subscription_not_eligible, cancel_at_period_end, payment_pending, unsupported_interval, extra_accounts_not_configured.
      - `reason` string, nullable
      - `trialing` boolean
      - `interval` 'month' | 'year', nullable
      - `included_accounts` integer: Accounts included with Agency (100).
      - `admin_granted_accounts` integer
      - `paid_extra_accounts` integer, required
      - `account_limit` integer, required
      - `accounts_in_use` integer, required
      - `highest_accounts_in_use` integer: Most connected accounts in any workspace the owner owns.
      - `min_paid_extra_accounts` integer: The lowest total of paid extra accounts allowed right now.
      - `min_purchase` integer, required: Every increase must add at least this many (20).
      - `price_per_account_cents` integer, nullable
      - `price_per_account` string, nullable
      - `recurring_cents` integer, nullable: Recurring cost of the current paid extra accounts per interval.
      - `payment_pending` ExtraAccountsPaymentPending
        - `hosted_invoice_url` string, nullable, required: Stripe-hosted payment page. The owner completes 3D Secure or retries the card there.
        - `requested_extra_accounts` integer, required: The total that applies once the invoice is paid.
        - `amount_due_cents` integer, nullable
        - `expires_at` string, date-time, nullable: Stripe discards the pending change after this time.

## Other responses

- `401`: Invalid or missing API key
- `403`: Request is authenticated but not allowed
- `404`: Resource not found
- `429`: Too many requests

---

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