A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Billing
description: Start premium and gift checkouts and receive Stripe webhook events.
---
import RouteHeader from '@/components/RouteHeader.astro';
These routes start a premium purchase on Stripe and receive Stripe's events. Checkout finishes on Stripe's pages, and the checkout routes return a URL for the browser to open. Entitlement state and subscription self-service are on [Premium](/http-api/premium/).
The checkout routes only work while [billing is on](/http-api/deployment-availability/), and the webhook only works while Stripe and its webhook secret are set up. Both checkout routes are user-only. A bot token gets 403 `ACCESS_DENIED`.
## Redirect URL object
The checkout routes and the billing portal route return this object. Open `url` in the browser.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| url | string | The URL to open in the browser |
### Example
```json
{
"url": "https://checkout.example.com/c/pay/cs_test_9f8e7d6c5b4a"
}
```
## Refund eligibility object
[Premium state](/http-api/premium/#get-premium-state) returns this object as `billing.refund_eligibility`. Self-hosted instances have no self-service refunds and always return the values below.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| eligible | boolean | Always false |
| reason | ?string | Always `feature_unavailable` |
| invoice_id | ?string | Always null |
| invoice_amount_paid_cents | ?integer | Always null |
| currency | ?string | Always null |
| paid_at | ?ISO8601 timestamp | Always null |
| refund_window_expires_at | ?ISO8601 timestamp | Always null |
| cooldown_expires_at | ?ISO8601 timestamp | Always null |
| cancels_subscription | boolean | Always false |
| provider | ?string | Always null |
## Webhook received object
The acknowledgement [Receive Stripe webhook](#receive-stripe-webhook) returns.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| received | boolean | Always true |
## Create subscription checkout
<RouteHeader method="POST" path="/v1/stripe/checkout/subscription" />
Creates a recurring premium checkout session and returns a [redirect URL](#redirect-url-object) object.
If the account already has an `active` or `trialing` subscription and `price_id` is the price for the other billing cycle, Fluxer schedules the switch for the end of the current period and creates no checkout session. It clears a pending cancellation, sends [User Update](/gateway/events/#user-update) and returns the web app's premium callback URL.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| price_id | string | Stripe price ID of a monthly or yearly premium plan (1-256 characters) |
| country_code?<sup>1</sup> | string | Two-letter country code that picks the price catalog (2 characters) |
| client_geoip_country_code? | string | Two-letter country code the client detected, saved with the purchase (2 characters) |
| eu_withdrawal_waiver_accepted? | boolean | Whether the user accepted the EU withdrawal waiver for digital content |
| payment_method?<sup>2</sup> | string | Either `card`, `pix` or `upi` (default `card`) |
| is_business? | boolean | Whether to require a billing address for tax invoicing (default false) |
| distribution?<sup>3</sup> | string | [Distribution](/http-api/premium/#distributions) the app build was sold through, such as `ios_marketplace` (up to 64 characters) |
| distribution_token? | string | Purchase token from that distribution, kept for reporting (up to 4096 characters) |
<sup>1</sup> Fluxer uses this only when it can't find the request's country. With prices set in environment config, a price in a currency other than USD or EUR needs it.
<sup>2</sup> With prices set in environment config, `pix` needs a BRL price and `upi` needs an INR price. Prices saved in the instance billing settings accept only `card`.
<sup>3</sup> With an active rule for the distribution, checkout charges its channel price, and `price_id` can be the standard price or the channel price from [get price IDs](/http-api/premium/#get-price-ids). Any other value pays the standard price.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [redirect URL](#redirect-url-object) object | The session was created or the billing cycle change was scheduled |
| 400 | [error response](/http-api/#error-response) | `STRIPE_INVALID_PRODUCT` for an unknown price |
| 400 | [error response](/http-api/#error-response) | `STRIPE_INVALID_PRODUCT_CONFIGURATION` for a gift price, a wrong catalog or a bad `payment_method` |
| 400 | [error response](/http-api/#error-response) | `UNCLAIMED_ACCOUNT_CANNOT_MAKE_PURCHASES` for an unclaimed account |
| 400 | [error response](/http-api/#error-response) | `STRIPE_ERROR` when Stripe rejects the request |
| 403 | [error response](/http-api/#error-response) | `PURCHASE_EMAIL_VERIFICATION_REQUIRED` for an unverified email address |
| 403 | [error response](/http-api/#error-response) | `PREMIUM_PURCHASE_BLOCKED` with a `reason` in the table below |
A `PREMIUM_PURCHASE_BLOCKED` error has a top-level `reason` field. For `existing_subscription`, it also has `subscription_status` with the status of that subscription.
| Reason | Condition |
| --- | --- |
| purchase_disabled | Purchases are disabled for the account |
| lifetime | The account has lifetime premium |
| existing_subscription | The customer already has a subscription that is `active`, `trialing`, `past_due`, `unpaid`, `incomplete` or `paused` |
Premium changes only after [Receive Stripe webhook](#receive-stripe-webhook) gets the matching event.
The rate limit is 3 requests per minute, on the `stripe:checkout:subscription` bucket.
## Create gift checkout
<RouteHeader method="POST" path="/v1/stripe/checkout/gift" />
Creates a one-time premium gift checkout session and returns a [redirect URL](#redirect-url-object) object. The account checks from [Create subscription checkout](#create-subscription-checkout) apply, but lifetime premium or an existing subscription doesn't block a gift.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| price_id | string | Stripe price ID of a gift (1-256 characters) |
| country_code?<sup>1</sup> | string | Two-letter country code that picks the price catalog (2 characters) |
| client_geoip_country_code? | string | Two-letter country code the client detected, saved with the purchase (2 characters) |
| eu_withdrawal_waiver_accepted? | boolean | Whether the user accepted the EU withdrawal waiver for digital content |
| is_business? | boolean | Whether to require a billing address for tax invoicing (default false) |
| payment_method? | string | Ignored by this route (`card`, `pix` or `upi`) |
| distribution?<sup>2</sup> | string | [Distribution](/http-api/premium/#distributions) the app build was sold through, such as `ios_marketplace` (up to 64 characters) |
| distribution_token? | string | Purchase token from that distribution, kept for reporting (up to 4096 characters) |
<sup>1</sup> Fluxer uses this only when it can't find the request's country. With prices set in environment config, a price in a currency other than USD or EUR needs it.
<sup>2</sup> With an active rule for the distribution, checkout charges its channel price, and `price_id` can be the standard price or the channel price from [get price IDs](/http-api/premium/#get-price-ids). Any other value pays the standard price.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [redirect URL](#redirect-url-object) object | The session was created |
| 400 | [error response](/http-api/#error-response) | `STRIPE_INVALID_PRODUCT` for an unknown price |
| 400 | [error response](/http-api/#error-response) | `STRIPE_INVALID_PRODUCT_CONFIGURATION` for a recurring price or a wrong catalog |
| 400 | [error response](/http-api/#error-response) | `UNCLAIMED_ACCOUNT_CANNOT_MAKE_PURCHASES` for an unclaimed account |
| 400 | [error response](/http-api/#error-response) | `STRIPE_ERROR` when Stripe rejects the request |
| 403 | [error response](/http-api/#error-response) | `PURCHASE_EMAIL_VERIFICATION_REQUIRED` for an unverified email address |
| 403 | [error response](/http-api/#error-response) | `PREMIUM_PURCHASE_BLOCKED` with `reason` set to `purchase_disabled` |
The [gift](/http-api/gifts/#gift-object) shows up in [List current user gifts](/http-api/users/gifts/#list-current-user-gifts) after Stripe confirms the payment.
The rate limit is 3 requests per minute, on the `stripe:checkout:gift` bucket.
## Receive Stripe webhook
<RouteHeader method="POST" path="/v1/stripe/webhook" unauthenticated />
Accepts a signed Stripe event and returns a [webhook received](#webhook-received-object) object. Stripe signs the raw body, and a proxy that changes the body breaks the signature.
### Request headers
| Field | Type | Description |
| --- | --- | --- |
| Stripe-Signature | string | Stripe signature over the raw request body |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [webhook received](#webhook-received-object) object | The event was verified and queued |
| 400 | [error response](/http-api/#error-response) | `STRIPE_WEBHOOK_SIGNATURE_MISSING` without the header, `STRIPE_WEBHOOK_NOT_AVAILABLE` when the Stripe client is not set up |
| 401 | [error response](/http-api/#error-response) | `STRIPE_WEBHOOK_SIGNATURE_INVALID` when the signature does not verify |
| 500 | [error response](/http-api/#error-response) | The event could not be queued |
Fluxer returns 200 before it processes the event and processes an event Stripe sends twice only once. It sends [User Update](/gateway/events/#user-update) for any account change the event causes.
The rate limit is 300 requests per minute, on the `stripe:webhook` bucket.