UC_4.6.3: Settings — Billing

---

Document References

---

1. Overview

Design: Figma — Billing, node 1-15026

2. Trigger

• The trader clicks the user chip in the sidebar footer → selects Settings (Ref: UC_4.1.2 §2 Screen Description, row 6) → selects the Billing tab.

3. Pre-conditions

• The trader is authenticated and inside the Dashboard shell (Ref: UC_4.1.1 §1 Overview).
• A Users record exists for the trader. No invoice is required — a trader with zero invoices reaches the empty state (Ref: BR_4.6.3.11).

4. Post-conditions

• The trader has read their payment history. No system state changes.
• The active sort column and the current page are not persisted. The next time the trader opens the tab, the table returns to its defaults: sort Date descending, page 1 (Ref: BR_4.6.3.9, BR_4.6.3.10).

5. Basic Flow

1. The trader lands on the Account screen and selects the Billing tab.
2. The table enters its loading state — column headers visible, 5 skeleton rows, pagination bar and footer note hidden (Ref: BR_4.6.3.11).
3. The frontend calls GET /billing-history with limit = 15, page = 1, sort_by = created_at, sort_dir = desc (Ref: BR_4.6.3.2).
4. The backend groups the line items by invoice_id, sorts, slices the page, and returns {items, page} (Ref: BR_4.6.3.3).
5. The frontend renders each item as one row of five columns — Invoice ID (Ref: BR_4.6.3.4), Date as MMM DD, YYYY in UTC (Ref: BR_4.6.3.8), Amount (Ref: BR_4.6.3.7), Status as a badge (Ref: BR_4.6.3.6), Description as the concatenated fee_type string of the line items (Ref: BR_4.6.3.5).
6. The pagination bar renders when page.total > 15; the footer note renders below it (Ref: BR_4.6.3.10).
7. The trader reads the table, and may sort it (Ref: §6 Alternative Flow A) or page through it (Ref: §6 Alternative Flow B).

6. Alternative Flows

Alternative Flow A — Trader sorts the table

1. The trader clicks the Date or Amount column header. No other header is clickable (Ref: BR_4.6.3.9).
2. The frontend re-calls GET /billing-history with the new sort_by and sort_dir, and page = 1.
3. The table enters its loading state, then renders page 1 of the new order and updates the sort indicator on the header.

Alternative Flow B — Trader pages through the table

1. The trader clicks a page number, ‹ Prev, or Next › (Ref: BR_4.6.3.10).
2. The frontend re-calls GET /billing-history — a page number sends page, ‹ Prev / Next › send cursor — keeping sort_by / sort_dir unchanged.
3. The table enters its loading state, then renders the new page and updates the Showing [start]–[end] of [total] invoices counter.

7. Exceptional Flow

8. Business Rules

BR_4.6.3.1: Tab scope

• The Billing tab holds one content block: the Invoice History table.
• No [Manage Billing] button, no billing portal, no redirect off the Dashboard.
• No card management, no subscription list, no cancel action and no funding-source switch — all of it belongs to the Market Data Management tab (Ref: UC_4.17.1).
• No PDF, no download, no print, no per-invoice detail view. A trader who needs a receipt uses the email receipt sent by the payment gateway.

BR_4.6.3.2: Data contract — Get Billing History

• The backend owns grouping, sorting and paging. The frontend does not group, does not sort and does not slice pages itself.
• page.total is the total number of grouped invoices, not the total number of rows in the database.
• The UI renders a page-number list, so the backend must support jumping directly to any page via the page parameter, not only sequential forward/backward movement via cursor (Ref: BR_4.6.3.10).

BR_4.6.3.3: Invoice grouping — one transaction, one row

• One checkout produces exactly one parent invoice_id. Every line item of that transaction — evaluation/reset/rebuy/extension, the market data feeds, and the TAX row — shares this invoice_id.
• Example: a trader buys 4 market data feeds in one transaction → the database holds 4 rows (MARKET_DATA_BASE for CME, 3 × MARKET_DATA_ADDON for NYMEX / COMEX / CBOT) plus 1 TAX row, all under the same invoice_id.
• The backend groups these rows into one item before responding. The UI renders one row per transaction.
• total_amount = the sum of amount across all line items under that invoice_id, tax included. No proportional splitting, no tax allocation per feed.
• invoice_id is a column generated by the system in Table invoices: each checkout produces exactly one value, and every line item of that checkout carries it. This is the grouping ID and the ID displayed on the UI.
• checkout_id is returned by the payment gateway; the system only receives and stores it. One checkout has one checkout_id even when the trader buys several products. It is not used for grouping and is not displayed on the UI.
• The internal ID of each individual line item exists in the database only and is never displayed on the UI.

BR_4.6.3.4: Column set and field mapping

The table renders exactly the five columns below, in this order. No column may be added, removed or re-ordered.

BR_4.6.3.5: Description column

The Description cell displays the raw fee_type value verbatim — it is never mapped to any other text.

fee_type ENUM of the invoices table — 10 values:

EVAL_L1 · EVAL_L2 · EVAL_L5 · RESET · REBUY · EXTENSION · PLATFORM_FEE · MARKET_DATA_BASE · MARKET_DATA_ADDON · TAX

How the Description string of a row is built:

• Concatenate the fee_type of every line item under that invoice, separated by , .
• A repeated fee_type is shown once. Example: a transaction buying 4 feeds (1 × MARKET_DATA_BASE + 3 × MARKET_DATA_ADDON) plus tax → Description is MARKET_DATA_BASE, MARKET_DATA_ADDON, TAX.
• No value is dropped — TAX and PLATFORM_FEE are displayed verbatim too when the invoice carries such a line item.
• Display order follows the line-item order returned by the backend.
• A fee_type outside the list above is still displayed verbatim. The Description cell is never left blank.

Rendering: single line, overflow truncated with CSS, hover shows a tooltip carrying the full Description string. No wrapping — wrapping would break the 15-rows-per-page layout (Ref: BR_4.6.3.10).

BR_4.6.3.6: Status column — badges

• status sits at the grouped-invoice level, not at the line-item level.
• A value outside these three renders as plain text instead of a badge (Ref: §7 row 5).
• The table does not filter on status — all three badges are displayed.

BR_4.6.3.7: Amount column

• total_amount and currency are rendered together in one column.
• Format: currency symbol + value to 2 decimal places + comma thousands separators + currency code. Example: $49.00 USD, $1,250.00 USD. Ref: CR-11.
• Every invoice is denominated in USD.
• No wrapping, no truncation. No tooltip — this column does not apply the hover-tooltip rule of CR-11.

BR_4.6.3.8: Date column

BR_4.6.3.9: Trader sorts the table

BR_4.6.3.10: Pagination

BR_4.6.3.11: Table states

The section heading and the section subtitle stay visible in all four states.

BR_4.6.3.12: Records not displayed

• The table displays fees and refunds. It does not display payouts — the full payout history and its management live in a dedicated sub-tab, scoped to Day 2.
• A refund of a charge is not a payout: it keeps the original invoice_id and carries status = refunded, so it stays in the table with the Refunded badge.
• PLATFORM_FEE is an internal expense-tracking tag (Tradesea, Quantower, Sierra Chart, MotiveWave, ATAS…) — the trader does not pay it out of pocket, so it does not arise in a trader's billing history. If an invoice does carry a PLATFORM_FEE line item, the Description still displays it verbatim (Ref: BR_4.6.3.5).
• Level 3+ traders have their CME feed covered: the system does not create a MARKET_DATA_BASE record with amount = $0. Feed entitlement is managed by market_data_flags and market_data_billable in the Users table.

BR_4.6.3.13: Read-only screen

• No form, no input field, no save action, no dirty state, no edit or delete action on any row.
• The unsaved-changes navigation warning (Ref: CR-05 / CF-01) never fires from this tab.
• No client-side cache: the API is called on every entry to the tab.
• No polling, no WebSocket, no auto-refresh. An invoice raised while the trader is sitting on the tab only appears after the trader navigates away and back.

BR_4.6.3.14: Availability

• The tab renders and behaves identically for SIM and LIVE traders. No branching on account type.
• Only the data differs: a SIM trader has no MARKET_DATA_BASE / MARKET_DATA_ADDON invoices; a LIVE trader may carry every fee_type (Ref: BR_4.6.3.5).
• The tab stays reachable in every account state, including Hard Breach, read-only after resignation, and an account paused by the Zombie protocol.

9. Screen Description

9.1 Billing tab

9.2 Invoice History table — column specification

---

Changelog