Premium

Premium is the paid tier of a Fluxer account. Use these routes to read an account's entitlement and to manage its Stripe subscription. To buy premium, use the Billing routes.

Every route except get price IDs needs a user token. On a self-hosted instance, get premium state and set premium perks disabled always work, and the other routes need Stripe billing to be set up.

Premium types

Value	Name	Description
0	NONE	No premium entitlement
1	SUBSCRIPTION	A subscription or a gift
2	LIFETIME	Premium for life

Billing cycles

Value	Description
monthly	Billed every month
yearly	Billed every year

Display currencies

Currency fields are three-letter ISO 4217 codes. Each amount field is an integer in the minor unit of the currency field its description gives. ISK amounts also use two decimals, as in 59000 for ISK 590.

Price IDs object

The recurring and gift checkout prices for one country.

Structure

Field	Type	Description
monthly?	?string	The Stripe price ID of the monthly plan
yearly?	?string	The Stripe price ID of the yearly plan
gift_1_month?	?string	The Stripe price ID of the one-month gift
gift_1_year?	?string	The Stripe price ID of the one-year gift
monthly_amount_minor?	?integer	The monthly amount, in the minor unit of `currency`
yearly_amount_minor?	?integer	The yearly amount, in the minor unit of `currency`
gift_1_month_amount_minor?	?integer	The one-month gift amount, in the minor unit of `gift_currency`
gift_1_year_amount_minor?	?integer	The one-year gift amount, in the minor unit of `gift_currency`
currency	string	Display currency of the recurring prices
gift_currency¹	?string	Display currency of the gift prices

¹ Null when no currency has both gift prices set up, and gift checkout is unavailable then.

Current subscription price object

The price the account is billed against, and the current list price for the same billing cycle and currency.

Structure

Field	Type	Description
price_id	string	The price the account is billed against
amount_minor	integer	The amount charged, in the minor unit of `currency`
currency	string	Display currency of the charged amount
billing_cycle	string	Billing cycle of the subscription
is_grandfathered	boolean	Whether the account is billed against a price other than the current list price
list_amount_minor	?integer	The current list amount, in the minor unit of `currency`
list_price_id	?string	The current list price ID for the same billing cycle and currency

Pending subscription change object

A billing cycle change scheduled for the end of the current period.

Structure

Field	Type	Description
schedule_id	string	The Stripe subscription schedule ID
change_kind	string	Always `billing_cycle`
current_billing_cycle	?string	The current billing cycle
target_billing_cycle	string	The billing cycle that starts at `effective_at`
effective_at	ISO8601 timestamp	When the change takes effect
current_price_id	?string	The current price ID
target_price_id	?string	The price ID after the change
target_amount_minor	?integer	The amount of the target price, in the minor unit of `currency`
currency	?string	Display currency of the target price
initial_amount_minor	?integer	The amount of the first invoice after the change, in the minor unit of `currency`
recurring_amount_minor	?integer	The amount of each later invoice, in the minor unit of `currency`
credit_amount_minor	?integer	The credit applied to the first invoice, in the minor unit of `currency`

List price switch object

Whether the subscription can move to the current list price. A self-hosted instance never offers this switch.

Structure

Field	Type	Description
available	boolean	Always false
reason	?string	Always `feature_unavailable`
pending	boolean	Always false
current_price_id	?string	The price ID the subscription bills on today
current_amount_minor	?integer	The amount billed today, in the minor unit of `currency`
list_price_id	?string	The current list price ID for the same billing cycle and currency
list_amount_minor	?integer	The current list price amount, in the minor unit of `currency`
currency	?string	Display currency of both amounts
billing_cycle	?string	The billing cycle of the subscription
effective_at	?ISO8601 timestamp	The end of the current billing period

Premium state object

The account's entitlement and the billing and pricing data behind it. Gate premium features on effective.is_premium.

Structure

Field	Type	Description
actual	actual premium state object	The entitlement from billing alone
effective	effective premium state object	The entitlement premium feature checks read
billing	premium billing state object	The account's Stripe billing data
pricing	premium pricing state object	The checkout prices for the request's country
store	null	Always null
subscription_provider	?string	`stripe` when the account has an active Stripe subscription, or null

Actual premium state object

The entitlement the account has from billing, before disabled perks, operator overrides and the instance premium mode apply.

Structure

Field	Type	Description
premium_type	?integer	Premium type
premium_since	?ISO8601 timestamp	When premium access first started
premium_until	?ISO8601 timestamp	When premium access ends, including gift extensions, or null for lifetime
premium_will_cancel	boolean	Whether the subscription cancels at the end of the current period
premium_billing_cycle	?string	Billing cycle
premium_lifetime_sequence	?integer	Always null
premium_grace_ends_at	?ISO8601 timestamp	The end of grace access after a failed renewal or a subscription end
has_active_paid_premium	boolean	Whether paid premium access is active, including the grace period
is_visionary	boolean	Whether the entitlement is lifetime
has_ever_purchased	boolean	Whether the account has ever bought premium

Effective premium state object

The state that decides whether premium features are available. is_premium is always true when the instance premium mode is everyone. Otherwise it is false when the account has disabled its perks, true when an operator override applies, and in every other case it matches actual.has_active_paid_premium.

Structure

Field	Type	Description
is_premium	boolean	Whether premium features are available to the account
premium_type	?integer	The premium type, or `0` while `is_premium` is false
premium_since	?ISO8601 timestamp	When premium access started, or null while `is_premium` is false
premium_until	?ISO8601 timestamp	Same as in the actual premium state
premium_will_cancel	boolean	Same as in the actual premium state
premium_billing_cycle	?string	Same as in the actual premium state
premium_lifetime_sequence	?integer	Always null
premium_grace_ends_at	?ISO8601 timestamp	Same as in the actual premium state
premium_enabled_override	boolean	Whether an operator premium flag grants premium
premium_purchase_disabled	boolean	Whether purchases are disabled for the account, or billing isn't set up
premium_perks_disabled	boolean	Whether the account has disabled its own perks
self_hosted	boolean	Whether the instance is self-hosted
bot	boolean	Always false

Premium billing state object

The account's Stripe customer, subscription, invoices and payment methods.

Structure

Field	Type	Description
stripe_customer_id	?string	The Stripe customer ID
current_subscription_price	?current subscription price object	The price the account is billed against
pending_subscription_change	?pending subscription change object	The scheduled billing cycle change
list_price_switch	list price switch object	Whether the subscription can move to the list price
subscription	?billing subscription object	The current subscription
invoices	array[billing invoice]	Up to 12 recent invoices, newest first
invoices_has_more	boolean	Whether there are older invoices, which the customer portal shows
payment_methods	array[billing payment method]	The stored payment methods, default first
refund_eligibility	refund eligibility object	Always ineligible, with `reason` set to `feature_unavailable`

Billing subscription object

A Stripe subscription, with status, plan_interval and plan_currency in Stripe's own values.

Structure

Field	Type	Description
id	string	The Stripe subscription ID
status	?string	The subscription status
current_period_start	?ISO8601 timestamp	The start of the current billing period
current_period_end	?ISO8601 timestamp	The end of the current billing period
cancel_at_period_end	boolean	Whether the subscription cancels at the period end
cancel_at	?ISO8601 timestamp	The scheduled cancellation time
canceled_at	?ISO8601 timestamp	When the cancellation was requested
plan_interval	?string	`month` or `year`
plan_amount_minor	?integer	The price amount, in the minor unit of `plan_currency`
plan_currency	?string	The lowercase currency of the price
default_payment_method_id	?string	The payment method the subscription bills

Billing invoice object

A Stripe invoice.

Structure

Field	Type	Description
id	string	The Stripe invoice ID
number	?string	The invoice number
amount_due	integer	The amount due, in the minor unit of `currency`
amount_paid	integer	The amount paid, in the minor unit of `currency`
currency	string	The lowercase currency of the invoice
status	?string	The invoice status
created_at	?ISO8601 timestamp	When the invoice was created
paid_at	?ISO8601 timestamp	When the invoice was paid
billing_reason	?string	Why Stripe created the invoice
subscription_id	?string	The subscription that produced the invoice, or null for a one-off purchase
hosted_invoice_url	?string	The hosted invoice page
invoice_pdf	?string	The invoice PDF

Billing payment method object

A stored payment method, where the card fields are null for anything that isn't a card.

Structure

Field	Type	Description
id	string	The Stripe payment method ID
type	?string	The payment method type
card_brand	?string	The card brand
card_last4	?string	The last four digits of the card
card_exp_month	?integer	The card's expiry month
card_exp_year	?integer	The card's expiry year
is_default	boolean	Whether the method is the customer's default

Premium pricing state object

The checkout prices for the request's country.

Structure

Field	Type	Description
country_code	?string	The country used to pick the prices
localized	?price IDs object	The prices, or null when no currency for the country has both a monthly and a yearly price set up

Get price IDs

GET/v1/premium/price-ids

Unauthenticated

Returns the price IDs object for the request's country.

Query parameters

Field	Type	Description
country_code?	string	A two-letter country code, used when Fluxer can't locate the request

Response

Status	Body	Condition
200	price IDs object	The prices were returned
400	error response	`STRIPE_ERROR` when no currency for the country has both a monthly and a yearly price set up

The rate limit is 40 requests per 10 seconds, on the stripe:price:ids bucket.

Get premium state

GET/v1/premium/state

Returns the premium state object for the current account. This request can also update the Stripe default payment method so that the customer and the subscription use the same one.

Query parameters

Field	Type	Description
country_code?	string	A two-letter country code for `pricing`, used when Fluxer can't locate the request

Response

Status	Body	Condition
200	premium state object	The state was returned

The rate limit is 30 requests per 10 seconds, on the stripe:premium:state bucket.

Get current subscription price

GET/v1/premium/current-subscription-price

Returns the current subscription price object, or null when the account has no subscription or Fluxer can't look up its price.

Response

Status	Body	Condition
200	?current subscription price object	The price was returned, or null

The rate limit is 20 requests per 10 seconds, on the stripe:subscription:current_price bucket.

Set premium perks disabled

PATCH/v1/premium/perks-disabled

Turns the account's premium perks off or on without changing billing, and returns the premium state object. Fluxer sends User Update when the value changes.

JSON body

Field	Type	Description
disabled	boolean	Whether premium perks are disabled for the account

Response

Status	Body	Condition
200	premium state object	The state was returned

The rate limit is 10 requests per minute, on the stripe:premium:perks_disabled bucket.

Create customer portal

POST/v1/premium/customer-portal

Creates a Stripe billing portal session and returns a redirect URL object. Send the user to the URL to manage their payment methods, invoices and subscription.

Response

Status	Body	Condition
200	redirect URL object	The portal session was created
400	error response	`STRIPE_NO_PURCHASE_HISTORY` when the account has no Stripe customer

The rate limit is 5 requests per minute, on the stripe:customer_portal bucket.

End premium grace period

POST/v1/premium/grace/end

Ends the grace period after a failed renewal, and premium features stop at once. It does nothing when the account isn't in a grace period. Fluxer sends User Update when the grace period ends.

Response body

Field	Type	Description
success	boolean	Always true

Response

Status	Body	Condition
200	response body	The grace period ended, or there was none

The rate limit is 3 requests per minute, on the stripe:premium:grace:end bucket.

Cancel subscription

POST/v1/premium/cancel-subscription

Sets the subscription to cancel at the end of the current period and discards any pending billing cycle change. Premium stays active until then. Fluxer sends User Update.

Response

Status	Body	Condition
204	empty	The subscription will cancel at the period end
400	error response	`STRIPE_NO_ACTIVE_SUBSCRIPTION` or `STRIPE_SUBSCRIPTION_ALREADY_CANCELING`

The rate limit is 5 requests per minute, on the stripe:subscription:cancel bucket.

Reactivate subscription

POST/v1/premium/reactivate-subscription

Undoes a pending cancellation and discards any pending billing cycle change. Fluxer sends User Update.

Response

Status	Body	Condition
204	empty	The subscription was reactivated
400	error response	`STRIPE_NO_SUBSCRIPTION` or `STRIPE_SUBSCRIPTION_NOT_CANCELING`

The rate limit is 5 requests per minute, on the stripe:subscription:reactivate bucket.

Change subscription billing cycle

POST/v1/premium/change-subscription

Moves the subscription between monthly and yearly and clears a pending cancellation. With effective_at set to now, Fluxer charges or credits the prorated difference at once, and a change at period_end shows up as billing.pending_subscription_change in get premium state. Requesting the current cycle does nothing. Fluxer sends User Update.

JSON body

Field	Type	Description
billing_cycle	string	The target billing cycle
effective_at?	string	`now` or `period_end` (default `now`)

Response

Status	Body	Condition
204	empty	The change was applied or scheduled
400	error response	`STRIPE_NO_ACTIVE_SUBSCRIPTION` when the account has no subscription
400	error response	`STRIPE_INVALID_PRODUCT_CONFIGURATION` when the cycle has no price in the subscription's currency

The rate limit is 5 requests per minute, on the stripe:subscription:change bucket.

Cancel pending subscription change

POST/v1/premium/cancel-pending-subscription-change

Cancels a scheduled billing cycle change. Fluxer sends User Update when it cancels one.

Response

Status	Body	Condition
204	empty	The pending change was cancelled, or there was none
400	error response	`STRIPE_NO_ACTIVE_SUBSCRIPTION` when the account has no subscription

The rate limit is 5 requests per minute, on the stripe:subscription:change bucket.