Billing Resource

Payment and transaction structure

Billing Resource

The billing system handles payments for premium subscriptions and other purchasable items.

Payment Object

Structure

id · string · required

Unique payment/checkout session identifier

user_id · Snowflake · required

ID of the user making the payment

stripe_customer_id · string | null

Stripe customer identifier

payment_intent_id · string | null

Stripe payment intent ID

subscription_id · string | null

Stripe subscription ID (for recurring payments)

invoice_id · string | null

Stripe invoice ID

price_id · string | null

Stripe price ID for the product

product_type · string | null

Type of product purchased (e.g., “premium_monthly”, “premium_yearly”)

amount · integer · required

Payment amount in cents

currency · string · required

Three-letter ISO currency code (e.g., “USD”, “EUR”)

status · string · required

Payment status (see Payment Status)

is_gift · boolean · default: "false"

Whether this is a gift purchase

gift_code · string | null

Gift code if this is a gift purchase

created_at · ISO8601 timestamp · required

When the payment was initiated

completed_at · ISO8601 timestamp | null

When the payment was completed

version · integer · required

Version for optimistic concurrency control

Example Payment

{
  "id": "cs_test_a1b2c3d4e5f6",
  "user_id": "123456789012345678",
  "stripe_customer_id": "cus_abc123xyz",
  "payment_intent_id": "pi_abc123xyz",
  "subscription_id": "sub_abc123xyz",
  "invoice_id": "in_abc123xyz",
  "price_id": "price_premium_monthly",
  "product_type": "premium_monthly",
  "amount": 999,
  "currency": "USD",
  "status": "complete",
  "is_gift": false,
  "gift_code": null,
  "created_at": "2026-03-04T12:00:00.000Z",
  "completed_at": "2026-03-04T12:00:15.000Z",
  "version": 1
}

Payment Status

Product Types

Premium Subscriptions

Gift Codes

Subscription Management

Subscription Object

id · string · required

Stripe subscription ID

status · string · required

Subscription status: active, past_due, canceled, unpaid

current_period_start · ISO8601 timestamp · required

Start of the current billing period

current_period_end · ISO8601 timestamp · required

End of the current billing period

cancel_at_period_end · boolean · required

Whether the subscription will cancel at period end

canceled_at · ISO8601 timestamp | null

When the subscription was canceled

Billing Cycle

Payment Methods

Fluxer uses Stripe for payment processing and supports:

• Credit/Debit Cards (Visa, Mastercard, American Express, etc.)
• PayPal
• Apple Pay
• Google Pay
• Bank transfers (select regions)
• SEPA Direct Debit (Europe)

Endpoints

Create Checkout Session

POST /api/v1/billing/checkout

Create a Stripe checkout session for purchasing premium.

product_type · string · required

Product to purchase (e.g., “premium_monthly”)

is_gift · boolean · default: "false"

Whether this is a gift purchase

success_url · string

URL to redirect after successful payment

cancel_url · string

URL to redirect if payment is canceled

Response:

{
  "checkout_url": "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6",
  "session_id": "cs_test_a1b2c3d4e5f6"
}

Get Payment History

GET /api/v1/users/@me/billing/history

Retrieve payment history for the current user.

limit · integer · default: "20"

Number of payments to return (1-100)

before · string

Get payments before this payment ID

Get Current Subscription

GET /api/v1/users/@me/billing/subscription

Get details about the current premium subscription.

Cancel Subscription

POST /api/v1/users/@me/billing/subscription/cancel

Cancel the current subscription (remains active until period end).

feedback · string

Optional cancellation feedback

reason · string

Cancellation reason code

Reactivate Subscription

POST /api/v1/users/@me/billing/subscription/reactivate

Reactivate a canceled subscription before it expires.

Update Payment Method

POST /api/v1/users/@me/billing/payment-method

Update the payment method for the subscription.

Response:

{
  "setup_url": "https://billing.stripe.com/session/..."
}

Get Invoices

GET /api/v1/users/@me/billing/invoices

Retrieve past invoices.

limit · integer · default: "20"

Number of invoices to return (1-100)

Download Invoice

GET /api/v1/users/@me/billing/invoices/{invoice_id}/pdf

Download a PDF invoice.

Gift Codes

Gift codes allow users to give premium subscriptions to others.

Purchasing Gifts

1. Create a checkout session with is_gift: true
2. Complete payment
3. Receive a unique gift code
4. Share the code with the recipient

Redeeming Gifts

POST /api/v1/billing/redeem

Redeem a gift code.

code · string · required

Gift code to redeem

Response:

{
  "premium_type": 1,
  "premium_until": "2026-04-04T12:00:00.000Z",
  "redeemed": true
}

Gift Code Object

code · string · required

Unique gift code

product_type · string · required

Type of premium granted

redeemed · boolean · required

Whether the code has been redeemed

redeemed_by · Snowflake | null

User who redeemed the code

redeemed_at · ISO8601 timestamp | null

When the code was redeemed

expires_at · ISO8601 timestamp | null

When the code expires

Refunds

Refunds are handled on a case-by-case basis:

• Contact support within 14 days of purchase
• Refunds typically processed within 5-10 business days
• Subscription time is adjusted accordingly
• Abuse of refund system may result in restrictions

Webhooks

Stripe webhooks notify Fluxer of payment events:

• payment_intent.succeeded - Payment completed
• payment_intent.failed - Payment failed
• invoice.paid - Subscription invoice paid
• invoice.payment_failed - Subscription payment failed
• customer.subscription.updated - Subscription changed
• customer.subscription.deleted - Subscription ended

Tax and VAT

• Prices shown include applicable taxes
• VAT collected for EU customers
• Tax rates determined by billing address
• Invoices include tax breakdown

Currency Support

Supported currencies:

• USD (United States Dollar)
• EUR (Euro)
• GBP (British Pound)
• CAD (Canadian Dollar)
• AUD (Australian Dollar)
• JPY (Japanese Yen)

Prices automatically convert based on user location.

Security

• All payment processing handled by Stripe (PCI DSS Level 1)
• Fluxer never stores credit card numbers
• 3D Secure authentication for supported cards
• Encrypted connections (TLS 1.3)
• Fraud detection and prevention

Related Resources

• Premium - Premium features and benefits
• Users - User premium status