Creates a Stripe Checkout session in `subscription` mode (card payments only, quantity 1) for the authenticated user's Stripe customer and returns the hosted checkout URL to redirect the user to. After checkout Stripe redirects to `<Origin>/profile` on success and `<Origin>/support` on cancel, where `<Origin>` is the value of the request's `Origin` header. The handler does not validate `priceId` against the known plans; it is passed straight to Stripe. Page credits are derived from the price ID: the $5/month plan grants 1,000 pages, $10/month grants 2,000 pages and $50/month grants 10,000 pages per billing period. A price ID that is not one of the configured plan prices grants 0 page credits.

Lists the Stripe subscriptions of the authenticated user's customer across all statuses (including canceled ones) and returns details of the first one Stripe returns. If the customer has never had a subscription the response is just `{ "active": false }`. `active` is true only when the subscription status is exactly `active`. `plan.amount` is in major currency units (Stripe's `unit_amount` divided by 100) and `plan.name` falls back to "Standard Plan" when the Stripe price has no nickname. Use `subscription_id` with the cancel, reactivate and update endpoints.

Sets `cancel_at_period_end: true` on the subscription. The subscription is not terminated immediately: it stays usable, and the user keeps their remaining OCR page credits, until `current_period_end`. The handler verifies that the subscription belongs to the authenticated user's Stripe customer before changing it. Can be undone with the reactivate endpoint while the period is still running.

Sets `cancel_at_period_end: false` on a subscription that was previously scheduled to cancel, so it renews normally. The handler verifies that the subscription belongs to the authenticated user's Stripe customer before changing it.

Swaps the price on the subscription's first item to `newPriceId` (upgrade or downgrade). The handler verifies that the subscription belongs to the authenticated user's Stripe customer first; `newPriceId` is not validated against the known plans. The page-credit allowance is not changed by this call itself: when Stripe notifies the backend of the subscription update, the allowance of the current billing period is set to the new plan's credits (1,000 / 2,000 / 10,000 pages) while pages already used in the period are kept.

Lists the card payment methods attached to the authenticated user's Stripe customer. `is_default` is derived from the payment method's Stripe metadata (`metadata.is_default === "true"`), not from the customer's default payment method setting, and `POST /stripe/payment-methods/set-default` does not write that metadata.

Creates a Stripe SetupIntent (card only) for the authenticated user's Stripe customer and returns its client secret. Confirm it client-side with Stripe.js / the Stripe mobile SDK to attach a new card to the customer. Takes no request body.

Returns the total number of subscriptions with status `active` in the Stripe account. This is a platform-wide figure, not specific to any user, and the route is intentionally public because the site-wide campaign banner shows it to every visitor. The count is cached on the server for 5 minutes, so the value can be up to 5 minutes old; requests arriving while the cache is being refreshed share a single refresh. If the refresh from Stripe fails and a previously cached value exists, that cached value is returned instead of an error.

Sets the customer's `invoice_settings.default_payment_method` in Stripe, which is the card used for subscription renewals and overage invoices. The handler verifies that the payment method is attached to the authenticated user's Stripe customer first.

Detaches the payment method from the authenticated user's Stripe customer. The handler verifies that the payment method is attached to that customer first.

Returns the 10 most recent Stripe invoices of the authenticated user's customer (fixed limit, no pagination). This includes subscription invoices as well as the separate invoices created for OCR overage charges. `amount_paid` is in major currency units (Stripe's amount divided by 100).

Returns the page-credit status of the current billing period plus a summary of unresolved failed overage payments. `tierCredits` is the plan allowance (1,000 pages for $5/month, 2,000 for $10/month, 10,000 for $50/month; 0 for an unrecognised price), `remainingCredits` is `max(0, tierCredits - pagesUsed)` and `isInOverage` is true once `pagesUsed` exceeds `tierCredits`. Pages beyond the allowance are charged immediately at OCR time at 2 cents ($0.02) per page with a 2 cent minimum, on a separate Stripe invoice; `overageChargedCents` is the amount successfully collected so far in this period. Credits reset when a subscription renewal invoice is paid. A subscription that was canceled but is still inside its paid period still counts as a subscription. If there is no usage record for the period yet, one is created on the fly from the Stripe subscription. Users without a subscription get `hasSubscription: false` with zeroed counters and null dates. Users with the `editor` or `admin` role bypass billing entirely: they get `hasSubscription: true`, `isAdmin: true`, and unlimited credits (`tierCredits` and `remainingCredits` are serialised as `null` in JSON). As a side effect, previously failed overage payments whose Stripe invoice has since been paid are marked as successful.

Dry-run calculation of how an OCR job of `pageCount` pages would be billed; nothing is charged or recorded. Pages are first covered by the remaining credits of the current period (`freePages`); the rest are `overagePages`, costed at 2 cents ($0.02) per page with a 2 cent minimum (`estimatedCostCents`). Without an active subscription the response is `{ "canProcess": false, "reason": "No active subscription", "estimatedCostCents": 0 }`. For users with the `editor` or `admin` role the response has `isAdmin: true`, all pages free, a cost of 0 and `remainingCreditsAfter` serialised as `null` (unlimited).

Paginated log of the authenticated user's OCR jobs, newest first, across all billing periods. Each entry shows how many pages of the job were covered by plan credits (`freePages`) versus billed as overage (`overagePages`, `overageChargeCents`). `total` is the total number of log entries for the user. No maximum is enforced on `limit`.

Returns the overage charges of the current billing period whose payment failed and is still unpaid, newest first. Before responding, each failed entry with a Stripe invoice is re-checked against Stripe; entries whose invoice has since been paid are marked successful and dropped from the list. If the user has no active usage record (no subscription) the response is empty with zero totals. Use the `_id` of an entry with `POST /stripe/usage/retry-payment/:logId`.

Attempts to collect a failed OCR overage charge again. The handler verifies that the usage log belongs to the authenticated user. If the original Stripe invoice is still open it is paid; if it turns out to be paid already the log is simply marked successful; otherwise a new invoice for the same amount is created, finalised and charged to the customer's default payment method. Note that an unsuccessful retry is also returned with HTTP 200: check `success`. Possible `message` values with `success: false` are "Payment is not in failed status", "Payment failed", or the Stripe error message; with `success: true` they are "Payment successful" or "Payment was already completed". Takes no request body.

Combined eligibility check for OCR uploads. Returns `{ "canUpload": true }` when the user has an active subscription (or a canceled one still inside its paid period) and their unresolved failed overage payments for the current period total no more than 500 cents ($5.00). Otherwise returns `canUpload: false` with a `reason`: `"No active subscription"`, or `"UNPAID_BALANCE"` together with `unpaidBalance` (cents) and `failedPaymentCount`. Users with the `editor` or `admin` role always get `{ "canUpload": true, "isAdmin": true }`.