Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
20.1 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Premium
description: Premium prices, entitlement state, billing data and subscription self-service.
---

import RouteHeader from '@/components/RouteHeader.astro';

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](/http-api/billing/) routes.

Every route except [get price IDs](#get-price-ids) needs a user token. On a [self-hosted instance](/http-api/deployment-availability/), [get premium state](#get-premium-state) and [set premium perks disabled](#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](#display-currencies) of the recurring prices |
| gift_currency<sup>1</sup> | ?string | [Display currency](#display-currencies) of the gift prices |
| distribution | ?[price distribution](#price-distribution-object) object | The distribution whose channel prices these are, or null for the standard prices |

<sup>1</sup> Null when no currency has both gift prices set up, and gift checkout is unavailable then.

## Distributions

An app build sold through a store that keeps a share of each sale sends its distribution id, such as `ios_marketplace`, with [get price IDs](#get-price-ids), [get premium state](#get-premium-state) and the [checkout routes](/http-api/billing/#create-subscription-checkout). When the instance has an active rule for that id, the amounts and checkout use its channel price. The channel price is the standard price divided by one minus the rule's rate, rounded up to an amount Stripe accepts in that currency, so the amount left after the store's share is at least the standard price. An unknown, malformed or inactive id gets the standard price and never an error. Self-hosted instances have no rules until an admin adds one.

## Price distribution object

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | string | The distribution id |
| rate_bps | integer | The store's share in basis points, where 500 is 5% |
| rule_version | integer | The version of the rule the prices come from |

## 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](#display-currencies) of the charged amount |
| billing_cycle | string | [Billing cycle](#billing-cycles) 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](#billing-cycles) |
| target_billing_cycle | string | The [billing cycle](#billing-cycles) 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](#display-currencies) 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](#display-currencies) of both amounts |
| billing_cycle | ?string | The [billing cycle](#billing-cycles) 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](#actual-premium-state-object) object | The entitlement from billing alone |
| effective | [effective premium state](#effective-premium-state-object) object | The entitlement premium feature checks read |
| billing | [premium billing state](#premium-billing-state-object) object | The account's Stripe billing data |
| pricing | [premium pricing state](#premium-pricing-state-object) 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-types) |
| 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](#billing-cycles) |
| 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](/admin-api/instance/#premium-modes) 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](#premium-types), 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](#actual-premium-state-object) |
| premium_will_cancel | boolean | Same as in the [actual premium state](#actual-premium-state-object) |
| premium_billing_cycle | ?string | Same as in the [actual premium state](#actual-premium-state-object) |
| premium_lifetime_sequence | ?integer | Always null |
| premium_grace_ends_at | ?ISO8601 timestamp | Same as in the [actual premium state](#actual-premium-state-object) |
| premium_enabled_override | boolean | Whether an operator [premium flag](/admin-api/users/#premium-flags) 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 and payment methods.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| stripe_customer_id | ?string | The Stripe customer ID |
| current_subscription_price | ?[current subscription price](#current-subscription-price-object) object | The price the account is billed against |
| pending_subscription_change | ?[pending subscription change](#pending-subscription-change-object) object | The scheduled billing cycle change |
| list_price_switch | [list price switch](#list-price-switch-object) object | Whether the subscription can move to the list price |
| subscription | ?[billing subscription](#billing-subscription-object) object | The current subscription |
| documents | array | Always empty. A self-hosted instance issues no invoices or receipts of its own, so Stripe's receipt settings apply |
| payment_methods | array[[billing payment method](#billing-payment-method-object)] | The stored payment methods, default first |
| refund_eligibility | [refund eligibility](/http-api/billing/#refund-eligibility-object) 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 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](#price-ids-object) object | The prices, or null when no currency for the country has both a monthly and a yearly price set up |

## Get price IDs

<RouteHeader method="GET" path="/v1/premium/price-ids" unauthenticated />

Returns the [price IDs](#price-ids-object) 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 |
| distribution? | string | The [distribution](#distributions) the app build was sold through (up to 64 characters) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [price IDs](#price-ids-object) object | The prices were returned |
| 400 | [error response](/http-api/#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

<RouteHeader method="GET" path="/v1/premium/state" />

Returns the [premium state](#premium-state-object) 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 |
| distribution? | string | The [distribution](#distributions) for `pricing` (up to 64 characters) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [premium state](#premium-state-object) object | The state was returned |

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

## Get current subscription price

<RouteHeader method="GET" path="/v1/premium/current-subscription-price" />

Returns the [current subscription price](#current-subscription-price-object) 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](#current-subscription-price-object) 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

<RouteHeader method="PATCH" path="/v1/premium/perks-disabled" />

Turns the account's premium perks off or on without changing billing, and returns the [premium state](#premium-state-object) object. Fluxer sends [User Update](/gateway/events/#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](#premium-state-object) object | The state was returned |

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

## Create customer portal

<RouteHeader method="POST" path="/v1/premium/customer-portal" />

Creates a Stripe billing portal session and returns a [redirect URL](/http-api/billing/#redirect-url-object) object. Send the user to the URL to manage their payment methods, invoices and subscription.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [redirect URL](/http-api/billing/#redirect-url-object) object | The portal session was created |
| 400 | [error response](/http-api/#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

<RouteHeader method="POST" path="/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](/gateway/events/#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

<RouteHeader method="POST" path="/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](/gateway/events/#user-update).

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The subscription will cancel at the period end |
| 400 | [error response](/http-api/#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

<RouteHeader method="POST" path="/v1/premium/reactivate-subscription" />

Undoes a pending cancellation and discards any pending billing cycle change. Fluxer sends [User Update](/gateway/events/#user-update).

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The subscription was reactivated |
| 400 | [error response](/http-api/#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

<RouteHeader method="POST" path="/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](#get-premium-state). Requesting the current cycle does nothing. Fluxer sends [User Update](/gateway/events/#user-update).

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| billing_cycle | string | The target [billing cycle](#billing-cycles) |
| effective_at? | string | `now` or `period_end` (default `now`) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The change was applied or scheduled |
| 400 | [error response](/http-api/#error-response) | `STRIPE_NO_ACTIVE_SUBSCRIPTION` when the account has no subscription |
| 400 | [error response](/http-api/#error-response) | `STRIPE_INVALID_PRODUCT_CONFIGURATION` when the cycle has no price in the subscription's currency |
| 400 | [error response](/http-api/#error-response) | `STRIPE_BILLING_CYCLE_CHANGE_NEEDS_RESUBSCRIBE` when the subscription is paid with Pix or UPI, whose mandate covers one billing cycle and amount |

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

## Cancel pending subscription change

<RouteHeader method="POST" path="/v1/premium/cancel-pending-subscription-change" />

Cancels a scheduled billing cycle change. Fluxer sends [User Update](/gateway/events/#user-update) when it cancels one.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The pending change was cancelled, or there was none |
| 400 | [error response](/http-api/#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.