Web Store

The Seven Donor Tiers

Donor ranks are split into seven tiers from Peregrinus (entry) to Imperator (top). Each tier has both a monthly subscription and a lifetime purchase price. Lifetime is roughly 5 months of subscription — past that break-even, lifetime wins. All prices are USD.

What Each Perk Actually Does

How to Buy — The Web Flow

1. Sign in to the dashboard. The store uses Minecraft as the sole identity — sign in via the Discord-linked account flow, which resolves to your Minecraft UUID. Every purchase is then automatically delivered to that account.
2. Browse the store page at /store. Each tier has both a monthly and a lifetime option.
3. Click Buy. The frontend calls POST /api/store/checkout with the chosen productId and subscription flag. The backend resolves your PayNow customer ID (creating one on first purchase) and creates a checkout session.
4. Redirect to PayNow. The response is a single-use URL — you complete payment on PayNow's secure page.
5. Webhook delivery. On payment confirmation, PayNow fires a signed webhook (POST /api/webhooks/paynow) to Imperium. The plugin grants your in-game rank/Aureus within seconds.
6. Return to dashboard. You land back at /dashboard/subscription?checkout=success with your new tier visible.

Subscriptions vs Lifetime — Which to Pick?

The break-even calculation: lifetime cost ÷ monthly cost = months to break even. Peregrinus: $14.99 / $2.99 ≈ 5 months. Imperator: $149.99 / $29.99 ≈ 5 months. The ratio is consistent across tiers.

Gifting

You can buy a lifetime donor rank for another Minecraft account. Subscriptions cannot be gifted — a recurring subscription on someone else's account would charge your card forever with no cancellation path.

1. Use the gift flow on the store page, or call POST /api/store/gift-checkout directly with { productId, recipientUsername }.
2. The backend resolves the recipient username to a UUID via the player database (with a Mojang/PlayerDB fallback for accounts that have never joined). If the lookup fails, you get a clear error before payment.
3. The recipient's PayNow customer ID is attached as gift_to_customer_id, so the rank delivers to them — not you.
4. You cannot gift to yourself; the backend explicitly rejects buyerUuid === recipientUuid.

The Multi-Item Cart

For buyers grabbing multiple ranks (e.g. a Patrician for yourself + a Libertus gift for a friend), the cart endpoint POST /api/store/cart-checkout bundles everything into a single PayNow checkout:

• Up to 20 line items per cart.
• Each item has productId, quantity (1–99), optional subscription flag, optional giftRecipient username.
• Mixed carts are supported — subscriptions, lifetimes, and gifts in one transaction.
• You pay once; the webhook handles per-line delivery.

Aureus — The Premium Currency

Aureus (₲) is the premium currency. It is never minted by gameplay — the only sources are the web store (direct purchase or via donor monthly stipends) and the cursus-honorum prestige milestones (P10, P15, P20, P25).

What Aureus buys:

• /rankskip — bypass an entire prestige cycle. See Rank Roadmap.
• In-game donor rank purchases via /donor buy (uses tier.monthlyAureusCost() at USD × 100).
• Reserved for future premium-only features.

The wall is intentional — the EconomyService blocks depositPremium from gameplay paths. Only prestige_refund:gc (refunding a failed prestige withdrawal) and store/donor flows can credit Aureus.

Gift Cards

Gift cards are a store-credit balance tracked in your gc currency column (visible in /stats). They're redeemed at checkout on the web store — you can apply a gift card balance to any purchase (subscription, lifetime, or cart).

• Source: purchased on the store, given as promotional rewards by staff, or won in certain server events.
• Use: applied automatically at checkout up to the purchase total; any remainder stays in your balance.
• Not transferable: gift cards are bound to your account — you can't /pay them to another player.

Managing Your Subscription

The dashboard at /dashboard/subscription shows your current tier, the PayNow subscription ID, and renewal date. From there:

API Reference — All Store Endpoints

All endpoints require storeAuth — a valid Minecraft-linked session cookie. No anonymous purchases are allowed; this is what guarantees delivery to the right account.

Picking a Tier — Value Analysis

The biggest per-dollar jumps are at Plebeian (auto-sell starts at 10%) and Consul (auto-sell hits 100%, full cosmetic freedom). Eques and Patrician are intermediate steps. For pure mining efficiency:

• Best budget option: Peregrinus ($2.99/mo). 5% sell bonus + 75 Aureus is real value for the price of a coffee.
• Best mid-tier value: Libertus ($8.99/mo). Auto-sell 25% eliminates a chunk of manual selling, and the +15% sell is meaningful.
• Best endgame value: Imperator ($29.99/mo or $149.99 lifetime). 100% auto-sell + 40% XP + free cells + the exclusive emperor trail. For daily players, this is the "skip the grind" tier.
• Lifetime is the right call if you'll play 5+ months. Beyond that, subscription dollars exceed the one-time lifetime cost.

Quick Reference