get
/premium/stateGet 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.
get_premium_state
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| country_code | query | string |
Responses
200
Success
json
{
"type": "object",
"properties": {
"actual": {
"type": "object",
"properties": {
"premium_type": {
"anyOf": [
{
"$ref": "#/components/schemas/UserPremiumTypes"
},
{
"type": "null"
}
],
"description": "Actual subscription type before local perk disabling"
},
"premium_since": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO timestamp when actual premium access first started"
},
"premium_until": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO timestamp when actual premium access ends, including stacked gift time"
},
"premium_will_cancel": {
"type": "boolean",
"description": "Whether the subscription is set to cancel at period end"
},
"premium_billing_cycle": {
"anyOf": [
{
"enum": [
"monthly",
"yearly"
],
"type": "string",
"x-enumNames": [
"monthly",
"yearly"
]
},
{
"type": "null"
}
],
"description": "The actual recurring billing cycle, when known"
},
"premium_lifetime_sequence": {
"anyOf": [
{
"type": "integer",
"format": "int53"
},
{
"type": "null"
}
],
"description": "Visionary sequence number, when applicable"
},
"premium_grace_ends_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO timestamp when grace access ends, when applicable"
},
"has_active_paid_premium": {
"type": "boolean",
"description": "Whether paid premium access is currently active before local disabling"
},
"is_visionary": {
"type": "boolean",
"description": "Whether the actual premium entitlement is lifetime Visionary access"
},
"has_ever_purchased": {
"type": "boolean",
"description": "Whether the user has ever completed a premium purchase"
}
},
"required": [
"premium_type",
"premium_since",
"premium_until",
"premium_will_cancel",
"premium_billing_cycle",
"premium_lifetime_sequence",
"premium_grace_ends_at",
"has_active_paid_premium",
"is_visionary",
"has_ever_purchased"
]
},
"effective": {
"type": "object",
"properties": {
"is_premium": {
"type": "boolean",
"description": "Whether premium perks are currently effective for product gating"
},
"premium_type": {
"anyOf": [
{
"$ref": "#/components/schemas/UserPremiumTypes"
},
{
"type": "null"
}
],
"description": "Effective premium type used by product gates"
},
"premium_since": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Effective premium start timestamp exposed to the client"
},
"premium_until": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Effective premium end timestamp exposed to the client, including stacked gift time"
},
"premium_will_cancel": {
"type": "boolean",
"description": "Effective cancellation status exposed to the client"
},
"premium_billing_cycle": {
"anyOf": [
{
"enum": [
"monthly",
"yearly"
],
"type": "string",
"x-enumNames": [
"monthly",
"yearly"
]
},
{
"type": "null"
}
],
"description": "Effective recurring billing cycle, when known"
},
"premium_lifetime_sequence": {
"anyOf": [
{
"type": "integer",
"format": "int53"
},
{
"type": "null"
}
],
"description": "Effective Visionary sequence number, when applicable"
},
"premium_grace_ends_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Effective grace timestamp exposed to the client"
},
"premium_enabled_override": {
"type": "boolean",
"description": "Whether backend premium override is enabled"
},
"premium_purchase_disabled": {
"type": "boolean",
"description": "Whether premium purchase is disabled for this account"
},
"premium_perks_disabled": {
"type": "boolean",
"description": "Whether the user temporarily disabled premium perks"
},
"self_hosted": {
"type": "boolean",
"description": "Whether the instance treats all users as premium because it is self-hosted"
},
"bot": {
"type": "boolean",
"description": "Whether the account is a bot account with premium-equivalent service access"
}
},
"required": [
"is_premium",
"premium_type",
"premium_since",
"premium_until",
"premium_will_cancel",
"premium_billing_cycle",
"premium_lifetime_sequence",
"premium_grace_ends_at",
"premium_enabled_override",
"premium_purchase_disabled",
"premium_perks_disabled",
"self_hosted",
"bot"
]
},
"billing": {
"type": "object",
"properties": {
"stripe_customer_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"current_subscription_price": {
"anyOf": [
{
"$ref": "#/components/schemas/CurrentSubscriptionPriceResponse"
},
{
"type": "null"
}
]
},
"pending_subscription_change": {
"anyOf": [
{
"$ref": "#/components/schemas/PendingSubscriptionChangeResponse"
},
{
"type": "null"
}
]
},
"subscription": {
"anyOf": [
{
"$ref": "#/components/schemas/PremiumBillingSubscriptionResponse"
},
{
"type": "null"
}
]
},
"invoices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PremiumBillingInvoiceResponse"
}
},
"invoices_has_more": {
"type": "boolean"
},
"payment_methods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PremiumBillingPaymentMethodResponse"
}
},
"refund_eligibility": {
"$ref": "#/components/schemas/SelfServeRefundEligibilityResponse"
}
},
"required": [
"stripe_customer_id",
"current_subscription_price",
"pending_subscription_change",
"subscription",
"invoices",
"invoices_has_more",
"payment_methods",
"refund_eligibility"
]
},
"pricing": {
"$ref": "#/components/schemas/PremiumPricingState"
}
},
"required": [
"actual",
"effective",
"billing",
"pricing"
]
}400
Bad Request - The request was malformed or contained invalid data
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}401
Unauthorized - Authentication is required or the token is invalid
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}403
Forbidden - You do not have permission to perform this action
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}429
Too Many Requests - You are being rate limited
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RATE_LIMITED"
]
},
"message": {
"type": "string"
},
"retry_after": {
"type": "number",
"description": "Seconds to wait before retrying"
},
"global": {
"type": "boolean",
"description": "Whether this is a global rate limit"
}
},
"required": [
"code",
"message",
"retry_after"
]
}500
Internal Server Error - An unexpected error occurred
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}