---
title: "Get premium state"
method: GET
path: "/premium/state"
tags: ["Premium"]
---

# Get premium state

`GET /premium/state`

Returns the authenticated user actual premium entitlement, effective perk state, and mirrored billing data. When Stripe is enabled, missing payment-method mirror data may be repaired lazily.

## Query parameters

- `country_code` string — Two-letter country code for regional pricing

## Response `200`

Success

- PremiumStateResponse
  - `actual` object, required
    - `premium_type` 0 | 1 | 2, required — Premium subscription type
    - `premium_since` string, nullable, required — ISO timestamp when actual premium access first started
    - `premium_until` string, nullable, required — ISO timestamp when actual premium access ends, including stacked gift time
    - `premium_will_cancel` boolean, required — Whether the subscription is set to cancel at period end
    - `premium_billing_cycle` 'monthly' | 'yearly', nullable, required — The actual recurring billing cycle, when known
    - `premium_lifetime_sequence` integer, nullable, required — Visionary sequence number, when applicable
    - `premium_grace_ends_at` string, nullable, required — ISO timestamp when grace access ends, when applicable
    - `has_active_paid_premium` boolean, required — Whether paid premium access is currently active before local disabling
    - `is_visionary` boolean, required — Whether the actual premium entitlement is lifetime Visionary access
    - `has_ever_purchased` boolean, required — Whether the user has ever completed a premium purchase
  - `effective` object, required
    - `is_premium` boolean, required — Whether premium perks are currently effective for product gating
    - `premium_type` 0 | 1 | 2, required — Premium subscription type
    - `premium_since` string, nullable, required — Effective premium start timestamp exposed to the client
    - `premium_until` string, nullable, required — Effective premium end timestamp exposed to the client, including stacked gift time
    - `premium_will_cancel` boolean, required — Effective cancellation status exposed to the client
    - `premium_billing_cycle` 'monthly' | 'yearly', nullable, required — Effective recurring billing cycle, when known
    - `premium_lifetime_sequence` integer, nullable, required — Effective Visionary sequence number, when applicable
    - `premium_grace_ends_at` string, nullable, required — Effective grace timestamp exposed to the client
    - `premium_enabled_override` boolean, required — Whether backend premium override is enabled
    - `premium_purchase_disabled` boolean, required — Whether premium purchase is disabled for this account
    - `premium_perks_disabled` boolean, required — Whether the user temporarily disabled premium perks
    - `self_hosted` boolean, required — Whether the instance treats all users as premium because it is self-hosted
    - `bot` boolean, required — Whether the account is a bot account with premium-equivalent service access
  - `billing` object, required
    - `stripe_customer_id` string, nullable, required
    - `current_subscription_price` CurrentSubscriptionPriceResponse, nullable, required
      - `price_id` string, required — The Stripe price ID the user is currently billed against
      - `amount_minor` integer, required — The amount the user is actually charged, in the currency minor unit
      - `currency` 'USD' | 'EUR' | 'BRL' | 'INR' | 'PLN' | 'TRY', required — Currency of the charged amount
      - `billing_cycle` 'monthly' | 'yearly', required — The recurring billing cycle of the active subscription
      - `is_grandfathered` boolean, required — Whether the user is on a legacy price that no longer matches the current list price
      - `list_amount_minor` integer, nullable, required — The current list price for the same cycle/currency, in the currency minor unit
      - `list_price_id` string, nullable, required — The current list Stripe price ID for the same cycle/currency
    - `pending_subscription_change` PendingSubscriptionChangeResponse, nullable, required
      - `schedule_id` string, required — Stripe subscription schedule ID managing the pending change
      - `current_billing_cycle` 'monthly' | 'yearly', nullable, required — Current recurring billing cycle
      - `target_billing_cycle` 'monthly' | 'yearly', required — Recurring billing cycle that will start later
      - `effective_at` string, required — ISO timestamp when the pending change takes effect
      - `current_price_id` string, nullable, required — Current Stripe price ID, when known
      - `target_price_id` string, nullable, required — Stripe price ID that will be used after the change
      - `currency` 'USD' | 'EUR' | 'BRL' | 'INR' | 'PLN' | 'TRY', nullable, required — Currency for the pending change
      - `initial_amount_minor` integer, nullable, required — Estimated first invoice amount after one-time credits, in the currency minor unit
      - `recurring_amount_minor` integer, nullable, required — Estimated normal recurring amount after the first invoice, in the currency minor unit
      - `credit_amount_minor` integer, nullable, required — One-time credit applied to the first invoice, in the currency minor unit
    - `subscription` PremiumBillingSubscriptionResponse, required
      - `id` string, required
      - `status` string, nullable, required
      - `current_period_start` string, nullable, required
      - `current_period_end` string, nullable, required
      - `cancel_at_period_end` boolean, required
      - `cancel_at` string, nullable, required
      - `canceled_at` string, nullable, required
      - `plan_interval` string, nullable, required
      - `plan_amount_minor` integer, nullable, required
      - `plan_currency` string, nullable, required
      - `default_payment_method_id` string, nullable, required
    - `invoices` PremiumBillingInvoiceResponse[], required
      - `id` string, required
      - `number` string, nullable, required
      - `amount_due` integer, required
      - `amount_paid` integer, required
      - `currency` string, required
      - `status` string, nullable, required
      - `created_at` string, nullable, required
      - `paid_at` string, nullable, required
      - `billing_reason` string, nullable, required
      - `subscription_id` string, nullable, required
      - `hosted_invoice_url` string, nullable, required
      - `invoice_pdf` string, nullable, required
    - `invoices_has_more` boolean, required
    - `payment_methods` PremiumBillingPaymentMethodResponse[], required
      - `id` string, required
      - `type` string, nullable, required
      - `card_brand` string, nullable, required
      - `card_last4` string, nullable, required
      - `card_exp_month` integer, nullable, required
      - `card_exp_year` integer, nullable, required
      - `is_default` boolean, required
    - `refund_eligibility` SelfServeRefundEligibilityResponse, required
      - `eligible` boolean, required — Whether the authenticated user can self-serve refund their latest purchase right now
      - `reason` 'no_refundable_purchase' | 'outside_refund_window' | 'cooldown_active' | 'feature_unavailable', required
      - `invoice_id` string, nullable, required — Latest paid invoice considered for refund eligibility
      - `invoice_amount_paid_cents` integer, nullable, required — Amount paid on the latest invoice in the currency minor unit
      - `currency` string, nullable, required — Currency of the latest paid invoice
      - `paid_at` string, nullable, required — ISO timestamp the latest invoice was paid
      - `refund_window_expires_at` string, nullable, required — ISO timestamp after which the 3-day refund window closes
      - `cooldown_expires_at` string, nullable, required — ISO timestamp the 30-day cooldown ends, if currently active
      - `cancels_subscription` boolean, required — Whether issuing the refund will also cancel the active subscription
  - `pricing` PremiumPricingState, required
    - `country_code` string, nullable, required — Country code used to resolve localized prices
    - `localized` PriceIdsResponse, required
      - `monthly` string, nullable — Stripe price ID for the monthly subscription
      - `yearly` string, nullable — Stripe price ID for the yearly subscription
      - `gift_1_month` string, nullable — Stripe price ID for the 1 month gift
      - `gift_1_year` string, nullable — Stripe price ID for the 1 year gift
      - `monthly_amount_minor` integer, nullable — Monthly price amount in the currency minor unit
      - `yearly_amount_minor` integer, nullable — Yearly price amount in the currency minor unit
      - `gift_1_month_amount_minor` integer, nullable — Gift 1 month price amount in the currency minor unit
      - `gift_1_year_amount_minor` integer, nullable — Gift 1 year price amount in the currency minor unit
      - `currency` 'USD' | 'EUR' | 'BRL' | 'INR' | 'PLN' | 'TRY', required — Currency for the prices
      - `gift_currency` 'USD' | 'EUR' | 'BRL' | 'INR' | 'PLN' | 'TRY', required — Currency for gift prices
    - `base` PriceIdsResponse, required
      - `monthly` string, nullable — Stripe price ID for the monthly subscription
      - `yearly` string, nullable — Stripe price ID for the yearly subscription
      - `gift_1_month` string, nullable — Stripe price ID for the 1 month gift
      - `gift_1_year` string, nullable — Stripe price ID for the 1 year gift
      - `monthly_amount_minor` integer, nullable — Monthly price amount in the currency minor unit
      - `yearly_amount_minor` integer, nullable — Yearly price amount in the currency minor unit
      - `gift_1_month_amount_minor` integer, nullable — Gift 1 month price amount in the currency minor unit
      - `gift_1_year_amount_minor` integer, nullable — Gift 1 year price amount in the currency minor unit
      - `currency` 'USD' | 'EUR' | 'BRL' | 'INR' | 'PLN' | 'TRY', required — Currency for the prices
      - `gift_currency` 'USD' | 'EUR' | 'BRL' | 'INR' | 'PLN' | 'TRY', required — Currency for gift prices

## Other responses

- `400` — Bad Request - The request was malformed or contained invalid data
- `401` — Unauthorized - Authentication is required or the token is invalid
- `403` — Forbidden - You do not have permission to perform this action
- `429` — Too Many Requests - You are being rate limited
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.dev/fluxer/apis/fluxer-api.md) · [All operations](https://skmtc.dev/fluxer/apis/fluxer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fluxer/fluxer-api/revisions/d9c706133cc5/schema)