Billing

These routes take payment for premium, verify an account holder’s age, and refund the most recent purchase. Checkout and age verification each finish on the payment provider’s own pages, so those routes create the provider session and return its URL for the browser to open. Receive Stripe webhook takes the signed events the provider sends back. The Premium resource owns entitlement state, mirrored billing data and subscription self-service.

A self-hosted deployment never serves age verification or the refund routes, serves the checkout routes only while billing is active, and serves receive Stripe webhook while Stripe is serviceable, as deployment availability describes. All of them are user-only except receive Stripe webhook.

Every response is a Fluxer object

The responses are Fluxer redirect, eligibility, refund and acknowledgement objects. They copy only a few payment provider values, such as the identifiers on a refund and the invoice_id of a refund eligibility object.

Redirect URL object

One absolute URL that completes a billing operation in a browser. Create subscription checkout, create gift checkout and create age verification session all answer with it. The object has no session identifier, so a client sends the browser to the returned value.

Structure

Field	Type	Description
url1	string	Absolute URL that completes the operation in a browser

¹ Usually an externally hosted payment provider session URL. Create subscription checkout can answer with the Fluxer premium callback URL instead

Example

{
  "url": "https://checkout.example.com/c/pay/cs_test_9f8e7d6c5b4a"
}

Refund eligibility object

Whether the account’s most recent purchase can still be refunded without operator involvement. When no refundable purchase was resolved, eligible and cancels_subscription are false. invoice_id, invoice_amount_paid_cents, currency, paid_at and refund_window_expires_at are null. cooldown_expires_at still reports an active cooldown unless the reason is feature_unavailable. A client reads eligible and reason before rendering any amount or timestamp.

Structure

Field	Type	Description
eligible	boolean	Whether the latest purchase can be refunded through refund latest purchase
reason	?string	Refund ineligibility reason, or null when the purchase is eligible
invoice_id1	?string	Payment provider invoice ID, or null when no refundable purchase was resolved
invoice_amount_paid_cents2	?integer	Invoice amount paid in the currency minor unit
currency3	?string	Lowercase provider currency of the invoice
paid_at4	?ISO8601 timestamp	Time the invoice payment settled
refund_window_expires_at5	?ISO8601 timestamp	End of the refund window
cooldown_expires_at6	?ISO8601 timestamp	End of the account refund cooldown, or null when no cooldown is active
cancels_subscription7	boolean	Whether refunding the invoice also cancels the subscription that produced it

¹ The first invoice among the five most recent invoices of the account’s payment provider customer that is paid, has a positive amount, and resolves a payment intent or a charge

² The field name states cents, but the value is always the minor unit of the invoice currency

³ Reported as usd when the resolved invoice has no currency of its own

⁴ Taken from the settlement time of the resolved invoice payment, and from the invoice creation time when that payment has no settlement timestamp

⁵ The value of paid_at plus exactly three days

⁶ The account’s first self-service refund time plus exactly 30 days, and null once that instant has passed

⁷ True when the resolved invoice was produced by a subscription, which the confirmed refund then cancels immediately

Example

{
  "eligible": true,
  "reason": null,
  "invoice_id": "in_1QaBcDeFgHiJkLmN",
  "invoice_amount_paid_cents": 499,
  "currency": "usd",
  "paid_at": "2026-08-29T11:04:12.000Z",
  "refund_window_expires_at": "2026-09-01T11:04:12.000Z",
  "cooldown_expires_at": null,
  "cancels_subscription": true
}

Refund ineligibility reasons

Value	Description
no_refundable_purchase	The account has no paid invoice with a positive amount and a resolvable payment reference among the invoices considered
outside_refund_window	The latest refundable purchase settled more than 3 days ago
cooldown_active	The account made a self-service refund less than 30 days ago
feature_unavailable	The deployment is self-hosted, or the payment provider is not configured, so self-service refunds are not offered

Refund object

The refund that refund latest purchase created against the resolved invoice. It describes the request the provider accepted, so status decides whether money has moved.

Structure

Field	Type	Description
invoice_id	string	Payment provider invoice ID that was refunded
payment_intent_id	?string	Payment provider payment intent ID, or null when the invoice resolved only a charge
charge_id	?string	Payment provider charge ID, or null when the invoice resolved only a payment intent
refund_id	?string	Payment provider refund ID of the created refund
refunded_amount_cents1	integer	Amount refunded so far in the invoice currency minor unit
invoice_amount_paid_cents	integer	Amount paid on the refunded invoice in the invoice currency minor unit
currency2	string	Lowercase provider currency of the invoice
subscription_id3	?string	Payment provider subscription that was cancelled along with the refund
status4	?string	Provider status of the refund

¹ Zero until the provider confirms the refund succeeded. Once confirmed it is the amount the provider accepted, which is one minor unit short of invoice_amount_paid_cents when the charge was paid with Pix and the invoice amount is greater than one minor unit

² Reported as usd when the resolved invoice has no currency of its own

³ Null while the refund is still pending, and null for a one-off purchase

⁴ The provider value, such as pending, succeeded or failed. Money moves only once it is succeeded

Example

{
  "invoice_id": "in_1QaBcDeFgHiJkLmN",
  "payment_intent_id": "pi_3QaBcDeFgHiJkLmN",
  "charge_id": null,
  "refund_id": "re_3QaBcDeFgHiJkLmN",
  "refunded_amount_cents": 499,
  "invoice_amount_paid_cents": 499,
  "currency": "usd",
  "subscription_id": "sub_1QaBcDeFgHiJkLmN",
  "status": "succeeded"
}

Webhook received object

The acknowledgement receive Stripe webhook returns once it authenticates the event and queues it for asynchronous processing.

Structure

Field	Type	Description
received	boolean	Always true after the event is authenticated and accepted for processing

Example

{
  "received": true
}

Create subscription checkout

POST/v1/stripe/checkout/subscription

Creates a recurring premium checkout session and returns a redirect URL object.

Limitations

• An unknown price returns 400 STRIPE_INVALID_PRODUCT.
• A gift price, a price outside the resolved country catalogue, and an omitted country code for a price that requires one all return 400 STRIPE_INVALID_PRODUCT_CONFIGURATION.
• An unclaimed account returns 400 UNCLAIMED_ACCOUNT_CANNOT_MAKE_PURCHASES.
• An unverified email address returns 403 PURCHASE_EMAIL_VERIFICATION_REQUIRED.
• The purchase-disabled premium flag returns 403 PREMIUM_PURCHASE_BLOCKED with the reason purchase_disabled.
• A lifetime Visionary account cannot buy a recurring subscription and returns 403 PREMIUM_PURCHASE_BLOCKED with the reason lifetime.
• An account with an active in-app purchase subscription returns the same code with the reason existing_subscription and the store in the top-level provider member. Fluxer never converts this refusal.
• An account whose payment provider customer already holds a subscription in the active, trialing, past_due, unpaid, incomplete or paused state returns the same code with the reason existing_subscription, unless Fluxer converts the purchase into a scheduled billing cycle change, as described below.

reason is a top-level member of the error response, and an existing_subscription refusal also has the blocking status in the top-level subscription_status member.

Fluxer evaluates the lifetime refusal before the unclaimed account, unverified email and purchase flag refusals, so a lifetime Visionary account submitting a recurring price always receives the reason lifetime whatever its account state.

An account already holding an active or trialing subscription can submit a registered recurring non-gift price for the other billing cycle. Fluxer then schedules a billing cycle change to the submitted cycle at the end of the current period. That is exactly what change subscription billing cycle with effective_at set to period_end does. The response is 200 with url set to the Fluxer premium callback URL.

The conversion requires a stored billing cycle on the account that differs from the submitted price’s cycle. Any other blocking subscription status, no stored billing cycle, and a matching cycle all still produce 403 PREMIUM_PURCHASE_BLOCKED. When scheduling the change fails, the caller receives that failure.

JSON body

Field	Type	Description
price_id	string	Registered recurring price ID (1-256 characters)
country_code?1	string	Two-letter country used to select the regional price catalogue (2 characters)
client_geoip_country_code?2	string	Two-letter country the client previously observed for itself (2 characters)
eu_withdrawal_waiver_accepted?3	boolean	Whether the digital content withdrawal waiver was explicitly accepted
payment_method?4	string	Either card, pix or upi (default card)
is_business?	boolean	Whether to require a billing address for tax invoicing (default false)

¹ Read only when Fluxer cannot geolocate the request, because the request-time geolocation country wins. The resolved country is required whenever the price is not in USD or EUR, and the price is validated against the catalogue for that country, so a client cannot buy outside the catalogue of the country it is browsing from

² Read to resolve the effective country for the withdrawal waiver, and recorded with the payment

³ Considered only when the effective country is inside the European Union or European Economic Area. The effective country is the request-time geolocation country, then the client-observed country, then the pricing country

⁴ pix requires a BRL recurring price and upi requires an INR recurring price. Both are rejected for a gift price or a non-recurring price with 400 STRIPE_INVALID_PRODUCT_CONFIGURATION. A recurring BRL price from the Fluxer price catalogue always checks out with pix, whatever this field says. A catalogue the operator manages has no such rule

Response

Status	Body	Condition
200	redirect URL object	The checkout session was created, or a blocked purchase was converted into a scheduled billing cycle change
4005	error response	The price, the account, or the payment provider blocks the checkout
403	error response	The email address is unverified, or the purchase is blocked
404	error response	The authenticated account record no longer exists

⁵ The price is unknown or not valid for the resolved catalogue, the account is unclaimed, the payment provider is not configured, or the payment provider rejected the request and returns STRIPE_ERROR

Side effects

Checkout collects the required consent, tax information and any promotion code on the provider’s pages.

A converted purchase schedules a billing cycle change instead of opening checkout. It clears pending cancellation and sends User Update to every account session.

Premium entitlement otherwise changes only after the matching signed event reaches receive Stripe webhook.

Rate limit

3 requests per minute for each authenticated user, on the stripe:checkout:subscription bucket.

Create gift checkout

POST/v1/stripe/checkout/gift

Creates a one-off premium gift checkout session and returns a redirect URL object.

Limitations

• The claimed account, verified email and purchase flag requirements of create subscription checkout apply unchanged, with the same codes.
• The submitted price is a registered gift price for the resolved country catalogue, so a recurring price returns 400 STRIPE_INVALID_PRODUCT_CONFIGURATION.

Neither the lifetime block nor the existing subscription block applies here, so a lifetime Visionary account can buy gifts.

JSON body

Field	Type	Description
price_id	string	Registered gift price ID (1-256 characters)
country_code?1	string	Two-letter country used to select the regional gift price catalogue (2 characters)
client_geoip_country_code?	string	Two-letter country the client previously observed for itself (2 characters)
eu_withdrawal_waiver_accepted?	boolean	Whether the digital content withdrawal waiver was explicitly accepted
is_business?	boolean	Whether to require a billing address for tax invoicing (default false)
payment_method?	string	Either card, pix or upi, which this operation ignores

¹ Read only when Fluxer cannot geolocate the request, because the request-time geolocation country wins. The resolved country is required whenever the gift price is not in USD or EUR

A submitted pix or upi is validated against the enum and then discarded. The session restricts no payment method type, so the provider offers whatever the deployment’s provider account accepts for the resolved currency.

Response

Status	Body	Condition
200	redirect URL object	The checkout session was created
4002	error response	The price, the account, or the payment provider blocks the checkout
403	error response	The email address is unverified, or the purchase is blocked
404	error response	The authenticated account record no longer exists

² The price is unknown or is not a gift price for the resolved catalogue, the account is unclaimed, the payment provider is not configured, or the payment provider rejected the request and returns STRIPE_ERROR

Side effects

The returned URL opens a one-off checkout. The gift appears in List current user gifts only after payment is confirmed.

Rate limit

3 requests per minute for each authenticated user, on the stripe:checkout:gift bucket.

Create age verification session

POST/v1/users/@me/age-verification

Creates a setup mode session that verifies the account holder controls a credit card, and returns a redirect URL object. It takes no request body.

Limitations

• A deployment with no configured provider returns 400 STRIPE_PAYMENT_NOT_AVAILABLE before any other check.
• An account that already has the age-verified adult flag then returns 400 AGE_VERIFICATION_ALREADY_VERIFIED.

Only a credit card satisfies verification

The session requests 3-D Secure authentication on the card and takes no payment. Verification succeeds only when the resulting payment method reports credit funding, and a debit or prepaid card leaves the account unverified without an error here.

Response

Status	Body	Condition
200	redirect URL object	The verification session was created
4001	error response	The account is already age verified, or the provider is not configured or rejected the request
404	error response	The authenticated account record no longer exists

¹ A rejected request returns STRIPE_ERROR

Side effects

Adult age verification is granted only after receive Stripe webhook processes the matching completion event and confirms a credit card. The grant sets the age-verified adult flag and sends User Update to every session owned by the account.

Rate limit

3 requests per minute for each authenticated user, on the age_verification bucket.

Get refund eligibility

GET/v1/premium/refund-eligibility

Returns the refund eligibility object for the authenticated account.

A deployment with no configured payment provider answers with eligible false and the reason feature_unavailable. Otherwise the operation lists the five most recent invoices for the account’s payment provider customer and selects the first that is paid, has a positive amount, and resolves a payment intent or a charge.

A failed payment-history lookup or an account with no payment history reports no refundable purchase.

The same object appears inside premium state

Get premium state also returns billing.refund_eligibility, which Fluxer computes from the invoices it has stored. This endpoint reads the invoices from the payment provider, so the premium state value can be older.

Response

Status	Body	Condition
200	refund eligibility object	The eligibility state was returned
404	error response	The authenticated account record no longer exists

Rate limit

30 requests per minute for each authenticated user, on the stripe:refund:eligibility bucket.

Refund latest purchase

POST/v1/premium/refund-latest

Refunds the account’s most recent eligible purchase and returns the refund object.

Limitations

• A deployment with no configured payment provider returns 400 STRIPE_PAYMENT_NOT_AVAILABLE.
• An account with no selectable invoice returns 400 STRIPE_NO_PURCHASE_HISTORY.
• A purchase that settled more than 3 days ago returns 403 STRIPE_REFUND_OUTSIDE_WINDOW.
• An account whose 30-day cooldown is still running returns 403 STRIPE_REFUND_COOLDOWN_ACTIVE.

The same invoice selection as get refund eligibility applies.

Repeating the request returns the same provider refund. After a refund that the provider reports as failed or cancelled, the account can attempt the refund again.

A Pix refund is short one minor unit

When the resolved charge was paid with Pix and the invoice amount is greater than one minor unit, the requested refund is the invoice amount minus one minor unit.

A confirmed refund is irreversible

Once the provider confirms the refund succeeded, the subscription that produced the invoice is cancelled immediately with no proration and no final invoice, and the 30-day cooldown begins. Neither effect can be undone through this API.

Response

Status	Body	Condition
200	refund object	The refund was created, or the request repeats an earlier refund of this invoice and returns that refund
4001	error response	The account has no refundable purchase, or the payment provider cannot refund it
403	error response	The purchase is outside the refund window, or the refund cooldown is active
404	error response	The authenticated account record no longer exists

¹ The payment provider is not configured, or the payment method could not be determined, or the provider rejected the refund. The last two return STRIPE_ERROR

Side effects

The operation creates a refund for the invoice amount paid, reduced by one minor unit in the Pix case, with the reason requested_by_customer.

A refund the provider confirms as succeeded in the same call cancels the subscription that produced the invoice and starts the 30-day cooldown from that moment. A refund still reported as pending or as awaiting further action does neither. Receive Stripe webhook cancels the subscription and starts the cooldown when it processes the provider event that confirms the refund.

A confirmed refund that cancels the current subscription updates the account’s premium state and sends User Update to every account session.

Rate limit

3 requests per minute for each authenticated user, on the stripe:refund:latest bucket.

Receive Stripe webhook

POST/v1/stripe/webhookUnauthenticated

Accepts a signed payment provider event for asynchronous processing and returns a webhook received object. The signature header is the credential.

Limitations

• A missing signature header returns 400 STRIPE_WEBHOOK_SIGNATURE_MISSING.
• A deployment with no payment provider client or webhook secret configured then returns 400 STRIPE_WEBHOOK_NOT_AVAILABLE.
• A signature header that does not verify returns 401 STRIPE_WEBHOOK_SIGNATURE_INVALID.

The signature covers the exact bytes

A proxy that re-encodes, reorders or pretty-prints the payload invalidates the signature.

Request headers

Field	Type	Description
Stripe-Signature	string	Payment provider signature computed over the exact raw request body

Response

Status	Body	Condition
200	webhook received object	The event was authenticated and queued
400	error response	The signature header is missing, or webhook processing is not configured for this deployment
401	error response	The signature did not verify against the raw body
500	error response	The event could not be queued

Side effects

The response comes before processing, and a redelivered event is applied once.

Accepted events update payment, subscription, gift, donation and age-verification results. Resulting account changes reach connected sessions as User Update.

Rate limit

300 requests per minute for each client IP address, or for the authenticated user when a credential happens to be supplied, on the stripe:webhook bucket. The bucket is exempt from the global bucket.