Ledgerline Billing, Marketplace & CRM — Combined Requirements & Build Specification

Product: Ledgerline — fintech platform-as-a-service (apps, external APIs, managed cloud) Stack: React 18 (web) · .NET 8 Web API · PostgreSQL 15 · EF Core 8 · Hangfire (workers) · Serilog Reference prototype: ledgerline-billing-prototype.html — open it. Every screen in this document is that prototype. Persona switcher top-right toggles provider console ↔ customer portal. Version: 1.0 · September 2026

How to use this document

Written to be handed to three audiences at once, and to be fed directly to an AI coding assistant.

Conventions used throughout

• Customer = the account (a fintech company that buys from us). Never called "client" in code.
• CustomerContact = a person at that account.
• CatalogItem = one sellable thing in the marketplace. Two categories only: App and API. There is no third category.
• SubscriptionItem = one CatalogItem attached to one Customer at an agreed price and term.
• Term is Monthly or Annual. There is no lifetime term. Enforced by a DB CHECK constraint.
• Every money column is NUMERIC(18,4), currency is USD everywhere, rounding to 2dp happens only at line and total level.
• Bold rules are non-negotiable invariants. They live in the domain layer and in DB constraints, not in the UI.

1. Executive summary

Today revenue is assembled by hand: someone reads a contract, opens a spreadsheet, remembers which modules a customer switched on last month, asks the cloud team what AWS cost, asks compliance how many Sumsub checks ran, and types an invoice. Setup fees get missed. Customers ask for a new module by email and nobody bills it for two months.

This project builds one system where the customer record is the master, and everything chargeable hangs off it:

Four things this spec insists on

1. One marketplace, two categories. Apps and APIs are rows in the same table with the same lifecycle. Adding a module is a data change, not a deploy.
2. The setup fee is tracked per subscription item, not per customer. The single most common billing bug in this product class: a customer-level "setup charged" flag means every module added after the first invoice is silently free forever.
3. An invoice is editable until it is raised, and never after. Discounts are applied at draft time, by a human, with an audit trail.
4. A customer request is a first-class object. The portal raises it, an admin approves it, and billing starts from the approval date — not from the request date, and not from a forgotten email.

Shape of the work. Roughly five months to full scope. The first working slice — onboard a customer, subscribe apps, raise and pay one invoice — lands in about six weeks.

2. Scope

2.1 In scope

2.2 Out of scope (v1, named so nobody assumes)

• Automated card/direct-debit collection. Payment is bank transfer or crypto, verified by a human.
• Multi-currency. Everything is USD. FX is a v2 item and the schema leaves room (currency_code columns exist and are constrained to 'USD').
• Revenue recognition / deferred revenue schedules for annual terms. v1 invoices annual up front and records it; ASC 606 schedules are v2.
• Automatic cloud cost ingestion from AWS/Azure/GCP billing APIs. v1 imports a monthly figure (manual entry or CSV); the connector is v2 and the schema is already shaped for it.
• Self-service signup. Accounts are created by our team.

2.3 Things that must never happen

These are the failure modes that cost money or trust. Each has a test named after it in §13.

• A setup fee billed twice for the same subscription item.
• A setup fee never billed because a customer-level flag was already set.
• A line edit applied to an invoice that has already been issued.
• Metered overage billed in advance, before the period closed.
• A request approved with billing backdated to the request date.
• Cloud rebilled at a markup the customer never agreed to, because the markup was read live instead of snapshotted onto the invoice line.
• A payment marked Paid without a reference that ties it to a bank statement or a chain transaction.

3. Domain model and vocabulary

Customer ─┬─ CustomerContact          (people)
          ├─ CustomerActivity         (meetings, calls, notes, follow-ups)
          ├─ Subscription ── SubscriptionItem ──> CatalogItem
          │                      └─ SubscriptionItemChange  (audit)
          ├─ ChangeRequest ──────────> CatalogItem
          ├─ CloudAccount ── CloudCostPeriod
          ├─ TxUsagePeriod ─────────> TxFeeRate
          ├─ ApiUsagePeriod ────────> CatalogItem (kind = Api)
          └─ Invoice ──┬─ InvoiceLine
                       ├─ InvoiceStatusHistory
                       └─ Payment

Vocabulary, fixed

4. Roles

Non-negotiable: cost columns (CloudCostPeriod.provider_cost, TxFeeRate.unit_cost) are never serialised into any portal response. Enforced by separate DTOs, and by an architecture test that fails the build if a portal controller returns a type containing those fields.

5. Data model

5.1 Conventions for every table

• Primary keys are uuid (gen_random_uuid()).
• Every table has created_at_utc timestamptz not null default now(), created_by uuid null.
• Mutable tables add updated_at_utc, updated_by, row_version bytea (EF concurrency token).
• Soft delete only where stated (is_archived bool); everything else is hard-deleted or never deleted.
• Every customer-scoped table carries customer_id and is indexed on it. Row-level security policy customer_isolation is enabled on portal-facing connections.

5.2 New tables

-- ═══════════════════════════════════════════════════════════
-- 5.2.1  CRM
-- ═══════════════════════════════════════════════════════════

CREATE TYPE customer_stage AS ENUM ('Lead','Discovery','Pilot','Live','Churned');
CREATE TYPE customer_status AS ENUM ('Prospect','Trial','Active','Suspended','Closed');
CREATE TYPE billing_cycle AS ENUM ('Monthly','Annual');

CREATE TABLE customer (
    customer_id        uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    code               text NOT NULL UNIQUE,              -- 'C-1001', human reference
    display_name       text NOT NULL,                     -- 'GlobalBridge'
    legal_name         text NOT NULL,                     -- 'GlobalBridge Financial Services Ltd'
    country_code       char(2) NOT NULL,
    website            text NULL,
    stage              customer_stage NOT NULL DEFAULT 'Lead',
    status             customer_status NOT NULL DEFAULT 'Prospect',
    owner_user_id      uuid NOT NULL,                     -- our staff, FK to identity
    source             text NULL,                         -- 'Inbound','Outbound','Referral','Partner','Event'
    tax_registration   text NULL,                         -- GST / VAT / EIN / TRN
    currency_code      char(3) NOT NULL DEFAULT 'USD' CHECK (currency_code = 'USD'),
    standard_discount_pct numeric(5,2) NOT NULL DEFAULT 0
                          CHECK (standard_discount_pct >= 0 AND standard_discount_pct <= 60),
    billing_cycle      billing_cycle NOT NULL DEFAULT 'Monthly',
    payment_terms_days int NOT NULL DEFAULT 14,
    cloud_managed      bool NOT NULL DEFAULT false,
    customer_since     date NULL,
    notes              text NULL,
    created_at_utc     timestamptz NOT NULL DEFAULT now(),
    updated_at_utc     timestamptz NULL,
    row_version        bytea NOT NULL DEFAULT '\x00'
);
CREATE INDEX ix_customer_stage  ON customer(stage) WHERE status <> 'Closed';
CREATE INDEX ix_customer_owner  ON customer(owner_user_id);

CREATE TABLE customer_contact (
    contact_id     uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    customer_id    uuid NOT NULL REFERENCES customer ON DELETE CASCADE,
    full_name      text NOT NULL,
    job_title      text NULL,
    email          citext NOT NULL,
    phone          text NULL,
    is_primary     bool NOT NULL DEFAULT false,
    is_billing     bool NOT NULL DEFAULT false,   -- receives invoices
    portal_user_id uuid NULL,                     -- set when they can log in
    is_archived    bool NOT NULL DEFAULT false,
    created_at_utc timestamptz NOT NULL DEFAULT now()
);
-- Exactly one primary contact per customer.
CREATE UNIQUE INDEX ux_contact_primary ON customer_contact(customer_id)
    WHERE is_primary AND NOT is_archived;
CREATE INDEX ix_contact_customer ON customer_contact(customer_id);

CREATE TYPE activity_type AS ENUM ('Meeting','Call','Note','Email');

CREATE TABLE customer_activity (
    activity_id     uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    customer_id     uuid NOT NULL REFERENCES customer ON DELETE CASCADE,
    type            activity_type NOT NULL,
    title           text NOT NULL,
    occurred_on     date NOT NULL,
    attendees       text NULL,                 -- free text; contact_ids in activity_attendee
    body            text NULL,
    follow_up_text  text NULL,
    follow_up_due   date NULL,
    follow_up_done  bool NOT NULL DEFAULT false,
    follow_up_done_at timestamptz NULL,
    logged_by       uuid NOT NULL,
    created_at_utc  timestamptz NOT NULL DEFAULT now(),
    CONSTRAINT ck_followup_pair CHECK (
        (follow_up_text IS NULL AND follow_up_due IS NULL) OR follow_up_text IS NOT NULL)
);
CREATE INDEX ix_activity_customer_date ON customer_activity(customer_id, occurred_on DESC);
CREATE INDEX ix_activity_open_followup ON customer_activity(follow_up_due)
    WHERE follow_up_text IS NOT NULL AND NOT follow_up_done;

CREATE TABLE activity_attendee (      -- optional join to real contacts
    activity_id uuid NOT NULL REFERENCES customer_activity ON DELETE CASCADE,
    contact_id  uuid NOT NULL REFERENCES customer_contact ON DELETE CASCADE,
    PRIMARY KEY (activity_id, contact_id)
);

-- ═══════════════════════════════════════════════════════════
-- 5.2.2  Marketplace catalog  (Apps + APIs, one table)
-- ═══════════════════════════════════════════════════════════

CREATE TYPE catalog_kind  AS ENUM ('App','Api');
CREATE TYPE billing_term  AS ENUM ('Monthly','Annual');   -- NO 'Lifetime'. Ever.
CREATE TYPE overage_basis AS ENUM ('PerCall','Per1000');

CREATE TABLE catalog_item (
    catalog_item_id  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    code             text NOT NULL UNIQUE,        -- 'AP01','AI03'
    kind             catalog_kind NOT NULL,
    group_name       text NOT NULL,               -- 'Apps' | 'External APIs'
    display_name     text NOT NULL,               -- 'Core & wallets'
    description      text NOT NULL,
    is_core          bool NOT NULL DEFAULT false, -- cannot be removed once subscribed
    setup_fee        numeric(18,4) NOT NULL DEFAULT 0 CHECK (setup_fee >= 0),
    price_monthly    numeric(18,4) NOT NULL CHECK (price_monthly >= 0),
    price_annual     numeric(18,4) NOT NULL CHECK (price_annual  >= 0),
    -- metering, APIs only
    included_calls   bigint NULL CHECK (included_calls >= 0),
    overage_rate     numeric(18,6) NULL CHECK (overage_rate >= 0),
    overage_basis    overage_basis NULL,
    sort_order       int NOT NULL DEFAULT 0,
    is_listed        bool NOT NULL DEFAULT true,  -- visible in portal marketplace
    is_sellable      bool NOT NULL DEFAULT true,  -- can be newly subscribed
    created_at_utc   timestamptz NOT NULL DEFAULT now(),
    updated_at_utc   timestamptz NULL,
    row_version      bytea NOT NULL DEFAULT '\x00',
    CONSTRAINT ck_group_matches_kind CHECK (
        (kind = 'App' AND group_name = 'Apps') OR
        (kind = 'Api' AND group_name = 'External APIs')),
    CONSTRAINT ck_api_metering CHECK (
        (kind = 'Api'  AND included_calls IS NOT NULL
                       AND overage_rate   IS NOT NULL
                       AND overage_basis  IS NOT NULL) OR
        (kind = 'App'  AND included_calls IS NULL
                       AND overage_rate   IS NULL
                       AND overage_basis  IS NULL))
);

-- List price changes are history, never an in-place overwrite of what was billed.
CREATE TABLE catalog_item_price_history (
    price_history_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    catalog_item_id  uuid NOT NULL REFERENCES catalog_item,
    effective_from   date NOT NULL,
    setup_fee        numeric(18,4) NOT NULL,
    price_monthly    numeric(18,4) NOT NULL,
    price_annual     numeric(18,4) NOT NULL,
    included_calls   bigint NULL,
    overage_rate     numeric(18,6) NULL,
    changed_by       uuid NOT NULL,
    reason           text NULL,
    created_at_utc   timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ix_price_history_item ON catalog_item_price_history(catalog_item_id, effective_from DESC);

-- ═══════════════════════════════════════════════════════════
-- 5.2.3  Subscriptions
-- ═══════════════════════════════════════════════════════════

CREATE TYPE subscription_status AS ENUM ('Trial','Active','Suspended','Cancelled');
CREATE TYPE setup_state         AS ENUM ('Due','Billed','Waived');

CREATE TABLE subscription (
    subscription_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    customer_id     uuid NOT NULL REFERENCES customer,
    status          subscription_status NOT NULL DEFAULT 'Trial',
    started_on      date NOT NULL,
    trial_ends_on   date NULL,
    cancelled_on    date NULL,
    created_at_utc  timestamptz NOT NULL DEFAULT now(),
    row_version     bytea NOT NULL DEFAULT '\x00'
);
-- One live subscription per customer. Historic cancelled ones may remain.
CREATE UNIQUE INDEX ux_subscription_live ON subscription(customer_id)
    WHERE status IN ('Trial','Active','Suspended');

CREATE TABLE subscription_item (
    subscription_item_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    subscription_id  uuid NOT NULL REFERENCES subscription ON DELETE CASCADE,
    customer_id      uuid NOT NULL REFERENCES customer,          -- denormalised for RLS + indexes
    catalog_item_id  uuid NOT NULL REFERENCES catalog_item,
    term             billing_term NOT NULL,
    -- Negotiated price. Defaults to catalog list price at the time of subscribing.
    unit_price       numeric(18,4) NOT NULL CHECK (unit_price >= 0),
    list_price_at_subscribe numeric(18,4) NOT NULL,              -- for "override vs list" reporting
    -- Setup fee is per item. This is the fix for the single worst bug in this product class.
    setup_fee        numeric(18,4) NOT NULL DEFAULT 0 CHECK (setup_fee >= 0),
    setup_state      setup_state NOT NULL DEFAULT 'Due',
    setup_billed_on_invoice_id uuid NULL,                        -- FK added after invoice table
    setup_waived_reason text NULL,
    -- Effective dating drives proration.
    effective_from   date NOT NULL,
    effective_to     date NULL,                                  -- NULL = still active
    term_renews_on   date NULL,                                  -- annual terms only
    source           text NOT NULL DEFAULT 'Admin',              -- 'Admin' | 'Onboarding' | 'Request'
    source_request_id uuid NULL,
    created_at_utc   timestamptz NOT NULL DEFAULT now(),
    updated_at_utc   timestamptz NULL,
    row_version      bytea NOT NULL DEFAULT '\x00',
    CONSTRAINT ck_setup_billed_ref CHECK (
        (setup_state = 'Billed' AND setup_billed_on_invoice_id IS NOT NULL) OR
        (setup_state <> 'Billed')),
    CONSTRAINT ck_setup_waived_reason CHECK (
        (setup_state = 'Waived' AND setup_waived_reason IS NOT NULL) OR
        (setup_state <> 'Waived')),
    CONSTRAINT ck_effective_range CHECK (effective_to IS NULL OR effective_to >= effective_from)
);
-- A customer cannot hold the same catalog item twice at the same time.
CREATE UNIQUE INDEX ux_subitem_active ON subscription_item(customer_id, catalog_item_id)
    WHERE effective_to IS NULL;
CREATE INDEX ix_subitem_customer ON subscription_item(customer_id);
CREATE INDEX ix_subitem_setup_due ON subscription_item(customer_id)
    WHERE setup_state = 'Due' AND effective_to IS NULL;

-- Every add / remove / term change / price override, append-only.
CREATE TYPE sub_change_kind AS ENUM ('Added','Removed','TermChanged','PriceChanged','SetupWaived');

CREATE TABLE subscription_item_change (
    change_id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    subscription_item_id uuid NOT NULL REFERENCES subscription_item ON DELETE CASCADE,
    customer_id uuid NOT NULL,
    kind        sub_change_kind NOT NULL,
    old_value   jsonb NULL,
    new_value   jsonb NULL,
    effective_on date NOT NULL,
    reason      text NULL,
    changed_by  uuid NOT NULL,
    created_at_utc timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ix_subchange_item ON subscription_item_change(subscription_item_id, created_at_utc DESC);

-- ═══════════════════════════════════════════════════════════
-- 5.2.4  Customer requests (portal → admin approval)
-- ═══════════════════════════════════════════════════════════

CREATE TYPE request_status AS ENUM ('Pending','Approved','Declined','Cancelled');

CREATE TABLE change_request (
    request_id       uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    code             text NOT NULL UNIQUE,            -- 'RQ-101'
    customer_id      uuid NOT NULL REFERENCES customer,
    catalog_item_id  uuid NOT NULL REFERENCES catalog_item,
    requested_term   billing_term NOT NULL,
    justification    text NULL,
    status           request_status NOT NULL DEFAULT 'Pending',
    requested_by_contact_id uuid NULL REFERENCES customer_contact,
    requested_at_utc timestamptz NOT NULL DEFAULT now(),
    decided_by       uuid NULL,
    decided_at_utc   timestamptz NULL,
    decision_note    text NULL,
    -- Set on approval. Billing starts here, never earlier.
    effective_from   date NULL,
    created_subscription_item_id uuid NULL REFERENCES subscription_item,
    quoted_price     numeric(18,4) NOT NULL,          -- price shown to customer when they asked
    quoted_setup_fee numeric(18,4) NOT NULL,
    row_version      bytea NOT NULL DEFAULT '\x00',
    CONSTRAINT ck_decision_fields CHECK (
        (status = 'Pending'  AND decided_at_utc IS NULL) OR
        (status <> 'Pending' AND decided_at_utc IS NOT NULL)),
    CONSTRAINT ck_approved_creates_item CHECK (
        (status = 'Approved' AND effective_from IS NOT NULL
                             AND created_subscription_item_id IS NOT NULL) OR
        (status <> 'Approved'))
);
-- One open request per customer per item. Stops double-requesting.
CREATE UNIQUE INDEX ux_request_open ON change_request(customer_id, catalog_item_id)
    WHERE status = 'Pending';
CREATE INDEX ix_request_pending ON change_request(status, requested_at_utc)
    WHERE status = 'Pending';

-- ═══════════════════════════════════════════════════════════
-- 5.2.5  Metering — API usage
-- ═══════════════════════════════════════════════════════════

-- Raw counters land daily (from the API gateway), aggregated per period for billing.
CREATE TABLE api_usage_daily (
    customer_id     uuid NOT NULL REFERENCES customer,
    catalog_item_id uuid NOT NULL REFERENCES catalog_item,
    usage_date      date NOT NULL,
    call_count      bigint NOT NULL DEFAULT 0 CHECK (call_count >= 0),
    error_count     bigint NOT NULL DEFAULT 0,
    ingested_at_utc timestamptz NOT NULL DEFAULT now(),
    source          text NOT NULL DEFAULT 'gateway',
    PRIMARY KEY (customer_id, catalog_item_id, usage_date)
);
CREATE INDEX ix_usage_daily_period ON api_usage_daily(customer_id, usage_date);

CREATE TYPE period_state AS ENUM ('Open','Closed','Billed');

CREATE TABLE api_usage_period (
    usage_period_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    customer_id     uuid NOT NULL REFERENCES customer,
    catalog_item_id uuid NOT NULL REFERENCES catalog_item,
    period_key      char(7) NOT NULL,                   -- '2026-09'
    call_count      bigint NOT NULL DEFAULT 0,
    -- Snapshots taken at close, so a later catalog price change cannot rewrite history.
    included_calls_snapshot bigint NOT NULL,
    overage_rate_snapshot   numeric(18,6) NOT NULL,
    overage_basis_snapshot  overage_basis NOT NULL,
    overage_units   numeric(18,4) NOT NULL DEFAULT 0,   -- calls, or thousands of calls
    overage_amount  numeric(18,4) NOT NULL DEFAULT 0,
    state           period_state NOT NULL DEFAULT 'Open',
    closed_at_utc   timestamptz NULL,
    billed_on_invoice_id uuid NULL,
    UNIQUE (customer_id, catalog_item_id, period_key)
);
CREATE INDEX ix_api_period_billable ON api_usage_period(period_key, state);

-- ═══════════════════════════════════════════════════════════
-- 5.2.6  Cloud rebilling
-- ═══════════════════════════════════════════════════════════

CREATE TYPE cloud_provider AS ENUM ('AWS','Azure','GCP','OCI');

CREATE TABLE cloud_account (
    cloud_account_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    customer_id      uuid NOT NULL REFERENCES customer,
    provider         cloud_provider NOT NULL,
    account_ref      text NOT NULL,                     -- AWS account id / Azure sub id / GCP project
    region           text NULL,
    markup_pct       numeric(5,2) NOT NULL DEFAULT 0
                     CHECK (markup_pct >= 0 AND markup_pct <= 100),
    note             text NULL,
    is_active        bool NOT NULL DEFAULT true,
    created_at_utc   timestamptz NOT NULL DEFAULT now(),
    updated_at_utc   timestamptz NULL,
    row_version      bytea NOT NULL DEFAULT '\x00',
    UNIQUE (provider, account_ref)
);
CREATE INDEX ix_cloud_customer ON cloud_account(customer_id) WHERE is_active;

CREATE TABLE cloud_cost_period (
    cloud_cost_id    uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    cloud_account_id uuid NOT NULL REFERENCES cloud_account,
    customer_id      uuid NOT NULL REFERENCES customer,
    period_key       char(7) NOT NULL,
    provider_cost    numeric(18,4) NOT NULL CHECK (provider_cost >= 0),  -- NEVER exposed to portal
    markup_pct_snapshot numeric(5,2) NOT NULL,          -- snapshot, not a live read
    rebill_amount    numeric(18,4) NOT NULL,            -- provider_cost * (1 + markup/100), 2dp
    source           text NOT NULL DEFAULT 'Manual',    -- 'Manual' | 'CSV' | 'Connector'
    evidence_url     text NULL,                         -- link to provider invoice PDF
    state            period_state NOT NULL DEFAULT 'Open',
    closed_at_utc    timestamptz NULL,
    billed_on_invoice_id uuid NULL,
    created_at_utc   timestamptz NOT NULL DEFAULT now(),
    UNIQUE (cloud_account_id, period_key)
);
CREATE INDEX ix_cloud_period_billable ON cloud_cost_period(period_key, state);

-- ═══════════════════════════════════════════════════════════
-- 5.2.7  Transaction fees (Sumsub, processing, issuance, payouts)
-- ═══════════════════════════════════════════════════════════

CREATE TABLE tx_fee_rate (
    tx_fee_rate_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    code           text NOT NULL UNIQUE,        -- 'SUMSUB_KYC'
    display_name   text NOT NULL,               -- 'Sumsub — KYC identity check'
    vendor         text NOT NULL,               -- 'Sumsub','Scheme','Ledgerline'
    unit_label     text NOT NULL,               -- 'check','screening','transaction','card','payout'
    unit_cost      numeric(18,6) NOT NULL CHECK (unit_cost >= 0),   -- NEVER exposed to portal
    unit_price     numeric(18,6) NOT NULL CHECK (unit_price >= 0),
    is_active      bool NOT NULL DEFAULT true,
    created_at_utc timestamptz NOT NULL DEFAULT now(),
    CONSTRAINT ck_price_ge_cost CHECK (unit_price >= unit_cost)     -- no negative margin by accident
);

-- Customer-specific override, optional. Falls back to tx_fee_rate.
CREATE TABLE customer_tx_fee_rate (
    customer_id    uuid NOT NULL REFERENCES customer,
    tx_fee_rate_id uuid NOT NULL REFERENCES tx_fee_rate,
    unit_price     numeric(18,6) NOT NULL,
    effective_from date NOT NULL,
    PRIMARY KEY (customer_id, tx_fee_rate_id, effective_from)
);

CREATE TABLE tx_usage_period (
    tx_usage_id    uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    customer_id    uuid NOT NULL REFERENCES customer,
    tx_fee_rate_id uuid NOT NULL REFERENCES tx_fee_rate,
    period_key     char(7) NOT NULL,
    quantity       numeric(18,4) NOT NULL DEFAULT 0 CHECK (quantity >= 0),
    unit_cost_snapshot  numeric(18,6) NOT NULL,
    unit_price_snapshot numeric(18,6) NOT NULL,
    cost_amount    numeric(18,4) NOT NULL DEFAULT 0,
    bill_amount    numeric(18,4) NOT NULL DEFAULT 0,
    state          period_state NOT NULL DEFAULT 'Open',
    source         text NOT NULL DEFAULT 'Manual',
    billed_on_invoice_id uuid NULL,
    UNIQUE (customer_id, tx_fee_rate_id, period_key)
);
CREATE INDEX ix_tx_period_billable ON tx_usage_period(period_key, state);

-- ═══════════════════════════════════════════════════════════
-- 5.2.8  Invoicing
-- ═══════════════════════════════════════════════════════════

CREATE TYPE invoice_type   AS ENUM ('Combined','AppsAndApis','Cloud','Transactions');
CREATE TYPE invoice_status AS ENUM ('Draft','Issued','PendingVerification','Paid','Overdue','Void');
CREATE TYPE line_category  AS ENUM ('Apps','Apis','Setup','Overage','Cloud','Transactions','Credit','Other');

CREATE TABLE invoice (
    invoice_id     uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    invoice_number text NULL UNIQUE,             -- NULL while Draft; assigned on raise
    customer_id    uuid NOT NULL REFERENCES customer,
    type           invoice_type NOT NULL,
    period_key     char(7) NOT NULL,             -- '2026-09'
    period_label   text NOT NULL,                -- 'Sept 2026', printed
    issue_date     date NULL,                    -- NULL while Draft
    due_date       date NULL,
    status         invoice_status NOT NULL DEFAULT 'Draft',
    currency_code  char(3) NOT NULL DEFAULT 'USD' CHECK (currency_code = 'USD'),
    -- Discount is an invoice-level human decision, captured with who and why.
    discount_pct   numeric(5,2) NOT NULL DEFAULT 0
                   CHECK (discount_pct >= 0 AND discount_pct <= 100),
    discount_reason text NULL,
    tax_label      text NOT NULL DEFAULT 'VAT',
    tax_pct        numeric(5,2) NOT NULL DEFAULT 0,
    -- Computed and frozen at raise time. Recomputed live while Draft.
    subtotal       numeric(18,4) NOT NULL DEFAULT 0,
    discount_amount numeric(18,4) NOT NULL DEFAULT 0,
    tax_amount     numeric(18,4) NOT NULL DEFAULT 0,
    total          numeric(18,4) NOT NULL DEFAULT 0,
    amount_paid    numeric(18,4) NOT NULL DEFAULT 0,
    notes          text NULL,                    -- printed on the invoice
    internal_note  text NULL,                    -- never printed, never sent to portal
    -- Snapshot of who we invoiced, so a later CRM edit does not rewrite history.
    bill_to_legal_name text NULL,
    bill_to_address    text NULL,
    bill_to_tax_reg    text NULL,
    bill_to_email      citext NULL,
    created_by     uuid NOT NULL,
    raised_by      uuid NULL,
    raised_at_utc  timestamptz NULL,
    voided_by      uuid NULL,
    void_reason    text NULL,
    created_at_utc timestamptz NOT NULL DEFAULT now(),
    updated_at_utc timestamptz NULL,
    row_version    bytea NOT NULL DEFAULT '\x00',
    CONSTRAINT ck_issued_has_number CHECK (
        (status = 'Draft' AND invoice_number IS NULL) OR
        (status <> 'Draft' AND invoice_number IS NOT NULL
                           AND issue_date IS NOT NULL AND due_date IS NOT NULL)),
    CONSTRAINT ck_discount_reason CHECK (discount_pct = 0 OR discount_reason IS NOT NULL)
);
CREATE INDEX ix_invoice_customer   ON invoice(customer_id, period_key);
CREATE INDEX ix_invoice_status     ON invoice(status) WHERE status IN ('Issued','Overdue','PendingVerification');
CREATE INDEX ix_invoice_drafts     ON invoice(created_by) WHERE status = 'Draft';
-- A customer gets at most one invoice of each type per period. Stops double-billing a month.
CREATE UNIQUE INDEX ux_invoice_customer_period_type ON invoice(customer_id, period_key, type)
    WHERE status <> 'Void';

CREATE TABLE invoice_line (
    invoice_line_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    invoice_id      uuid NOT NULL REFERENCES invoice ON DELETE CASCADE,
    line_no         int  NOT NULL,
    category        line_category NOT NULL,
    description     text NOT NULL,
    quantity        numeric(18,4) NOT NULL DEFAULT 1,
    unit_price      numeric(18,6) NOT NULL,        -- may be negative for Credit lines
    line_discount_pct numeric(5,2) NOT NULL DEFAULT 0
                      CHECK (line_discount_pct >= 0 AND line_discount_pct <= 100),
    amount          numeric(18,4) NOT NULL,        -- qty * unit_price * (1 - disc/100), 2dp
    -- Provenance. Nullable because a human can add a free-text line.
    source_kind     text NULL,                     -- 'SubscriptionItem','SetupFee','ApiOverage','CloudPeriod','TxPeriod','Manual'
    source_id       uuid NULL,
    period_from     date NULL,                     -- proration window, printed when partial
    period_to       date NULL,
    is_prorated     bool NOT NULL DEFAULT false,
    created_at_utc  timestamptz NOT NULL DEFAULT now(),
    UNIQUE (invoice_id, line_no),
    CONSTRAINT ck_credit_negative CHECK (
        (category = 'Credit' AND unit_price <= 0) OR (category <> 'Credit'))
);
CREATE INDEX ix_line_invoice ON invoice_line(invoice_id, line_no);
CREATE INDEX ix_line_source  ON invoice_line(source_kind, source_id);

-- Append-only. Nothing ever updates a row here.
CREATE TABLE invoice_status_history (
    history_id   bigserial PRIMARY KEY,
    invoice_id   uuid NOT NULL REFERENCES invoice ON DELETE CASCADE,
    from_status  invoice_status NULL,
    to_status    invoice_status NOT NULL,
    changed_by   uuid NOT NULL,
    reason       text NULL,
    snapshot     jsonb NOT NULL,          -- totals at the moment of transition
    created_at_utc timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ix_status_hist_invoice ON invoice_status_history(invoice_id, history_id);

-- Now the deferred FKs from §5.2.3/5.2.5/5.2.6/5.2.7:
ALTER TABLE subscription_item  ADD CONSTRAINT fk_subitem_setup_invoice
    FOREIGN KEY (setup_billed_on_invoice_id) REFERENCES invoice;
ALTER TABLE api_usage_period    ADD CONSTRAINT fk_apiperiod_invoice
    FOREIGN KEY (billed_on_invoice_id) REFERENCES invoice;
ALTER TABLE cloud_cost_period   ADD CONSTRAINT fk_cloudperiod_invoice
    FOREIGN KEY (billed_on_invoice_id) REFERENCES invoice;
ALTER TABLE tx_usage_period     ADD CONSTRAINT fk_txperiod_invoice
    FOREIGN KEY (billed_on_invoice_id) REFERENCES invoice;

CREATE TABLE credit_note (
    credit_note_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    credit_number  text NOT NULL UNIQUE,
    customer_id    uuid NOT NULL REFERENCES customer,
    against_invoice_id uuid NULL REFERENCES invoice,
    amount         numeric(18,4) NOT NULL CHECK (amount > 0),
    reason         text NOT NULL,
    issued_by      uuid NOT NULL,
    issued_at_utc  timestamptz NOT NULL DEFAULT now()
);

-- ═══════════════════════════════════════════════════════════
-- 5.2.9  Payments
-- ═══════════════════════════════════════════════════════════

CREATE TYPE payment_method AS ENUM ('BankTransfer','Crypto','Offset','WriteOff');
CREATE TYPE payment_state  AS ENUM ('Submitted','Verified','Rejected');

CREATE TABLE bank_account (
    bank_account_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    label           text NOT NULL,           -- 'Emirates NBD — primary USD'
    bank_name       text NOT NULL,
    beneficiary     text NOT NULL,
    account_number  text NOT NULL,
    iban            text NULL,
    swift_bic       text NOT NULL,
    branch_note     text NULL,
    currency_code   char(3) NOT NULL DEFAULT 'USD',
    is_active       bool NOT NULL DEFAULT true,
    sort_order      int NOT NULL DEFAULT 0
);

CREATE TABLE crypto_wallet (
    wallet_id      uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    asset          text NOT NULL,            -- 'USDT','USDC','BTC'
    chain          text NOT NULL,            -- 'Ethereum (ERC-20)','Tron (TRC-20)','Polygon','Bitcoin'
    address        text NOT NULL,
    memo_tag       text NULL,
    min_confirmations int NOT NULL DEFAULT 12,
    is_active      bool NOT NULL DEFAULT true,
    sort_order     int NOT NULL DEFAULT 0,
    UNIQUE (asset, chain, address)
);

-- A quote is locked when the payment screen renders, so the customer cannot be
-- charged a different crypto amount than the one they were shown.
CREATE TABLE crypto_quote (
    quote_id       uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    invoice_id     uuid NOT NULL REFERENCES invoice,
    wallet_id      uuid NOT NULL REFERENCES crypto_wallet,
    usd_amount     numeric(18,4) NOT NULL,
    asset_amount   numeric(28,10) NOT NULL,
    rate_usd       numeric(28,10) NOT NULL,
    rate_source    text NOT NULL,
    locked_at_utc  timestamptz NOT NULL DEFAULT now(),
    expires_at_utc timestamptz NOT NULL
);
CREATE INDEX ix_quote_invoice ON crypto_quote(invoice_id, locked_at_utc DESC);

CREATE TABLE payment (
    payment_id     uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    invoice_id     uuid NOT NULL REFERENCES invoice,
    customer_id    uuid NOT NULL REFERENCES customer,
    method         payment_method NOT NULL,
    state          payment_state NOT NULL DEFAULT 'Submitted',
    amount_claimed numeric(18,4) NOT NULL,
    amount_verified numeric(18,4) NULL,
    -- Bank
    bank_account_id uuid NULL REFERENCES bank_account,
    wire_reference  text NULL,
    -- Crypto
    wallet_id      uuid NULL REFERENCES crypto_wallet,
    quote_id       uuid NULL REFERENCES crypto_quote,
    tx_hash        text NULL,
    confirmations  int NULL,
    -- Audit
    submitted_by_contact_id uuid NULL REFERENCES customer_contact,
    submitted_at_utc timestamptz NOT NULL DEFAULT now(),
    verified_by    uuid NULL,
    verified_at_utc timestamptz NULL,
    rejected_reason text NULL,
    evidence_url   text NULL,
    row_version    bytea NOT NULL DEFAULT '\x00',
    CONSTRAINT ck_payment_reference CHECK (
        (method = 'BankTransfer' AND wire_reference IS NOT NULL) OR
        (method = 'Crypto'       AND tx_hash IS NOT NULL AND wallet_id IS NOT NULL) OR
        (method IN ('Offset','WriteOff'))),
    CONSTRAINT ck_verified_fields CHECK (
        (state = 'Verified' AND amount_verified IS NOT NULL AND verified_at_utc IS NOT NULL) OR
        (state <> 'Verified'))
);
-- The same chain transaction can only be claimed once, across all customers.
CREATE UNIQUE INDEX ux_payment_txhash ON payment(tx_hash)
    WHERE tx_hash IS NOT NULL AND state <> 'Rejected';
CREATE INDEX ix_payment_pending ON payment(state) WHERE state = 'Submitted';
CREATE INDEX ix_payment_invoice ON payment(invoice_id);

-- ═══════════════════════════════════════════════════════════
-- 5.2.10  Collections
-- ═══════════════════════════════════════════════════════════

CREATE TYPE dunning_step AS ENUM ('Reminder1','Reminder2','FinalNotice','Suspended');

CREATE TABLE dunning_event (
    dunning_id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    invoice_id   uuid NOT NULL REFERENCES invoice,
    customer_id  uuid NOT NULL REFERENCES customer,
    step         dunning_step NOT NULL,
    days_overdue int NOT NULL,
    channel      text NOT NULL,             -- 'Email','InApp'
    sent_to      citext NOT NULL,
    sent_at_utc  timestamptz NOT NULL DEFAULT now(),
    triggered_by text NOT NULL              -- 'Worker' | user id
);
CREATE INDEX ix_dunning_invoice ON dunning_event(invoice_id, sent_at_utc DESC);

-- ═══════════════════════════════════════════════════════════
-- 5.2.11  Platform settings and plumbing
-- ═══════════════════════════════════════════════════════════

CREATE TABLE billing_settings (              -- single row, id = 1
    id                   int PRIMARY KEY DEFAULT 1 CHECK (id = 1),
    company_legal_name   text NOT NULL,
    company_address      text NOT NULL,
    company_tax_line     text NOT NULL,
    billing_email        citext NOT NULL,
    tax_label            text NOT NULL DEFAULT 'VAT',
    tax_pct              numeric(5,2) NOT NULL DEFAULT 5,
    payment_terms_days   int NOT NULL DEFAULT 14,
    late_fee_pct_month   numeric(5,2) NOT NULL DEFAULT 1.5,
    dunning_days         int[] NOT NULL DEFAULT '{3,7,14}',
    suspend_after_days   int NOT NULL DEFAULT 30,
    annual_discount_note text NOT NULL DEFAULT 'Annual terms are priced 15% below twelve monthly payments.',
    invoice_number_format text NOT NULL DEFAULT 'INV-{yyyy}-{seq:0000}',
    updated_at_utc       timestamptz NULL,
    updated_by           uuid NULL
);

CREATE TABLE number_sequence (
    sequence_key text PRIMARY KEY,           -- 'invoice:2026', 'credit:2026', 'request'
    next_value   bigint NOT NULL DEFAULT 1
);

CREATE TABLE audit_log (
    audit_id     bigserial PRIMARY KEY,
    entity_type  text NOT NULL,
    entity_id    uuid NOT NULL,
    customer_id  uuid NULL,
    action       text NOT NULL,              -- 'Created','Updated','Raised','Verified','Approved'
    actor_id     uuid NOT NULL,
    actor_role   text NOT NULL,
    before_json  jsonb NULL,
    after_json   jsonb NULL,
    ip_address   inet NULL,
    created_at_utc timestamptz NOT NULL DEFAULT now(),
    prev_hash    bytea NULL,
    row_hash     bytea NOT NULL              -- sha256(prev_hash || canonical(row))
);
CREATE INDEX ix_audit_entity ON audit_log(entity_type, entity_id, audit_id);

CREATE TABLE outbox_message (
    message_id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    topic        text NOT NULL,
    payload      jsonb NOT NULL,
    available_at_utc timestamptz NOT NULL DEFAULT now(),
    attempts     int NOT NULL DEFAULT 0,
    processed_at_utc timestamptz NULL,
    last_error   text NULL
);
CREATE INDEX ix_outbox_pending ON outbox_message(available_at_utc)
    WHERE processed_at_utc IS NULL;

5.3 Enforce the invariants in the database, not only in code

Application code changes. Constraints do not.

-- 1. An invoice that is not a Draft is immutable except for status, payment and void fields.
CREATE OR REPLACE FUNCTION trg_invoice_immutable() RETURNS trigger AS $$
BEGIN
    IF OLD.status <> 'Draft' THEN
        IF (NEW.customer_id, NEW.type, NEW.period_key, NEW.discount_pct, NEW.tax_pct,
            NEW.subtotal, NEW.total, NEW.issue_date, NEW.due_date, NEW.invoice_number)
           IS DISTINCT FROM
           (OLD.customer_id, OLD.type, OLD.period_key, OLD.discount_pct, OLD.tax_pct,
            OLD.subtotal, OLD.total, OLD.issue_date, OLD.due_date, OLD.invoice_number)
        THEN
            RAISE EXCEPTION 'Invoice % is % and cannot be edited. Void it and raise a new one.',
                OLD.invoice_number, OLD.status;
        END IF;
    END IF;
    RETURN NEW;
END $$ LANGUAGE plpgsql;

CREATE TRIGGER invoice_immutable BEFORE UPDATE ON invoice
    FOR EACH ROW EXECUTE FUNCTION trg_invoice_immutable();

-- 2. Lines cannot be touched once the invoice has left Draft.
CREATE OR REPLACE FUNCTION trg_line_locked() RETURNS trigger AS $$
DECLARE s invoice_status;
BEGIN
    SELECT status INTO s FROM invoice
        WHERE invoice_id = COALESCE(NEW.invoice_id, OLD.invoice_id);
    IF s <> 'Draft' THEN
        RAISE EXCEPTION 'Cannot modify lines of a % invoice', s;
    END IF;
    RETURN COALESCE(NEW, OLD);
END $$ LANGUAGE plpgsql;

CREATE TRIGGER line_locked BEFORE INSERT OR UPDATE OR DELETE ON invoice_line
    FOR EACH ROW EXECUTE FUNCTION trg_line_locked();

-- 3. A setup fee can never go from Billed back to Due.
CREATE OR REPLACE FUNCTION trg_setup_no_regress() RETURNS trigger AS $$
BEGIN
    IF OLD.setup_state = 'Billed' AND NEW.setup_state <> 'Billed' THEN
        RAISE EXCEPTION 'Setup fee for subscription item % is already billed on invoice %',
            OLD.subscription_item_id, OLD.setup_billed_on_invoice_id;
    END IF;
    RETURN NEW;
END $$ LANGUAGE plpgsql;

CREATE TRIGGER setup_no_regress BEFORE UPDATE ON subscription_item
    FOR EACH ROW EXECUTE FUNCTION trg_setup_no_regress();

-- 4. Audit log and status history are append-only.
CREATE RULE audit_no_update AS ON UPDATE TO audit_log DO INSTEAD NOTHING;
CREATE RULE audit_no_delete AS ON DELETE TO audit_log DO INSTEAD NOTHING;
CREATE RULE hist_no_update  AS ON UPDATE TO invoice_status_history DO INSTEAD NOTHING;
CREATE RULE hist_no_delete  AS ON DELETE TO invoice_status_history DO INSTEAD NOTHING;

Why trigger 3 matters. The prototype's markSetupBilled() runs only when an invoice is raised, not when it is saved as a draft. Without a DB guard, a future "recalculate drafts" job could reset the flag and bill the same $6,000 twice. The constraint makes that impossible regardless of what the service layer does.

5.4 EF Core configuration notes

• Map every enum with HasPostgresEnum<T>() in OnModelCreating, not as strings.
• row_version → .IsRowVersion() on aggregates: Customer, Invoice, SubscriptionItem, ChangeRequest, Payment, CatalogItem, CloudAccount.
• Invoice owns InvoiceLine (OwnsMany is wrong here — use a real entity with cascade delete, because lines are queried directly for the AR report).
• Money: .HasPrecision(18, 4). Never double. Never decimal without precision.
• Global query filter for the portal connection: .HasQueryFilter(x => x.CustomerId == _ctx.CustomerId) on every customer-scoped entity, plus Postgres RLS as a second line of defence.
• Never .Include() CloudCostPeriod.ProviderCost in a portal-facing projection. Use explicit Select into portal DTOs.

6. The billing engine

6.1 One resolver, four call sites

public interface IChargeResolver
{
    // Pure. No DB writes. Given a customer and a period, produce the charge set.
    Task<ChargeSet> ResolveAsync(Guid customerId, PeriodKey period,
                                 InvoiceType type, CancellationToken ct);
}

All four must produce identical output for identical input. One golden-file test per scenario in §13.3.

6.2 The charge types

public sealed record ChargeSet(
    IReadOnlyList<Charge> Charges,
    IReadOnlyList<string> Warnings);     // e.g. "Cloud period 2026-09 still Open"

public sealed record Charge(
    LineCategory Category,
    string       Description,
    decimal      Quantity,
    decimal      UnitPrice,
    string?      SourceKind,
    Guid?        SourceId,
    DateOnly?    PeriodFrom,
    DateOnly?    PeriodTo,
    bool         IsProrated);

In advance vs in arrears is the rule that keeps the numbers honest. Recurring fees are charged for the month ahead. Everything metered is charged for the month behind. A September invoice therefore reads: September subscription + August overage + August cloud + August transaction fees. The invoice period_key is the issue period; each line carries its own period_from/period_to.

6.3 Proration

daily_rate      = unit_price / days_in_period
prorated_amount = round(daily_rate * chargeable_days, 2)
chargeable_days = days between max(effective_from, period_start)
                            and min(effective_to ?? period_end, period_end), inclusive

Rules:

1. Proration applies only to Monthly term items, and only in the period where effective_from or effective_to falls inside the period.
2. Annual items are not prorated month to month. They are billed in full on term_renews_on, and prorated only when the term starts mid-year.
3. A prorated line must set is_prorated = true and print its window: "Cards (monthly) — 12 Sept to 30 Sept".
4. Removing an item mid-period generates a credit line on the next invoice for the unused days, never a negative subscription line.
5. days_in_period uses the actual calendar month. No 30/360.

6.4 The setup-fee lifecycle — read this twice

This is the defect the prototype was corrected for, and it is worth stating as a state machine.

                 item created (admin, onboarding, or approved request)
                                    │
                                    ▼
                            ┌───────────────┐
              waive ───────▶│    Waived     │   (needs reason + finance role)
              (auth)        └───────────────┘
                                    ▲
                                    │
                            ┌───────────────┐        invoice raised
   setup_fee > 0  ─────────▶│      Due      │ ──────────────────────────▶ ┌────────┐
                            └───────────────┘   (line present, status      │ Billed │
                                    │            Draft → Issued)           └────────┘
                    item removed    │                                           │
                    before billing  ▼                                           │
                            ┌───────────────┐                     ✗ no transition out
                            │   (deleted)   │                       (DB trigger)
                            └───────────────┘

The rules, as invariants:

// The only correct implementation. Note: called inside the Raise transaction.
public async Task MarkSetupBilledAsync(Invoice invoice, CancellationToken ct)
{
    var setupItemIds = invoice.Lines
        .Where(l => l.Category == LineCategory.Setup && l.SourceKind == "SetupFee")
        .Select(l => l.SourceId!.Value)
        .ToHashSet();

    if (setupItemIds.Count == 0) return;

    var items = await _db.SubscriptionItems
        .Where(i => setupItemIds.Contains(i.SubscriptionItemId) && i.SetupState == SetupState.Due)
        .ToListAsync(ct);

    foreach (var item in items)
    {
        item.SetupState = SetupState.Billed;
        item.SetupBilledOnInvoiceId = invoice.InvoiceId;
    }
    // Any id in setupItemIds that was NOT Due is a bug: log it loudly, do not silently skip.
    var unexpected = setupItemIds.Except(items.Select(i => i.SubscriptionItemId)).ToList();
    if (unexpected.Count > 0)
        _log.LogError("Setup lines on {Invoice} referenced items not in Due state: {Ids}",
                      invoice.InvoiceNumber, unexpected);
}

6.5 Metering and overage

overage_units  = basis == Per1000
                 ? max(0, call_count - included_calls) / 1000.0
                 : max(0, call_count - included_calls)
overage_amount = round(overage_units * overage_rate, 2)

• included_calls, overage_rate and overage_basis are snapshotted onto api_usage_period when the period closes. A catalog price change in October must not alter what September's overage cost.
• Periods close on the 1st at 02:00 UTC via CloseUsagePeriodsWorker. Only Closed periods are billable.
• Overage never appears on an invoice for the current, open period. The portal may show running overage with the label "estimated, not yet billed".
• Tier changes mid-period: the allowance is prorated by days on each tier. Implement as two period rows with distinct snapshots when term/tier changes; simpler and auditable.

6.6 Cloud rebilling

rebill_amount = round(provider_cost * (1 + markup_pct / 100), 2)

• markup_pct_snapshot is written to cloud_cost_period at import time. The invoice reads the snapshot, never cloud_account.markup_pct.
• Line description is generated and includes the account ref and the markup so the customer can reconcile: "AWS 4471-9982-1130 — Sept 2026 usage incl. 12% management".
• provider_cost is never returned by any portal endpoint. The portal sees only rebill_amount.
• If evidence_url is set, the invoice PDF gets a "provider statement attached" note.

6.7 Transaction fees

cost_amount = round(quantity * unit_cost_snapshot,  2)     -- internal only
bill_amount = round(quantity * unit_price_snapshot, 2)
margin      = bill_amount - cost_amount                    -- internal only

Resolution order for unit_price: customer_tx_fee_rate (latest effective_from ≤ period end) → tx_fee_rate.unit_price.

6.8 Discounts and tax — the order of operations

This order is fixed. Changing it changes every invoice total in the system.

1.  line_amount    = round(qty × unit_price × (1 − line_discount_pct/100), 2)
2.  subtotal       = Σ line_amount
3.  discount_amount= round(subtotal × invoice.discount_pct / 100, 2)
4.  taxable_base   = subtotal − discount_amount
5.  tax_amount     = round(taxable_base × tax_pct / 100, 2)
6.  total          = taxable_base + tax_amount
7.  balance_due    = total − amount_paid

• Rounding is half away from zero, 2dp, at each numbered step. Never round once at the end.
• Line discount and invoice discount stack. A 10% line discount plus a 5% invoice discount on $1,000 is $855.00, not $850.00.
• discount_pct > 0 requires discount_reason. Enforced by CHECK.
• Discount authority: account owner ≤ 10%, billing operator ≤ 25%, finance admin any. Above your limit the Raise button is disabled with an explanation (AC-17.12).

6.9 Reference implementation, ported from the prototype

public static decimal LineAmount(decimal qty, decimal unitPrice, decimal lineDiscountPct)
    => Round2(qty * unitPrice * (1m - lineDiscountPct / 100m));

public static InvoiceTotals Totals(IEnumerable<InvoiceLine> lines,
                                   decimal invoiceDiscountPct, decimal taxPct)
{
    var subtotal = Round2(lines.Sum(l => l.Amount));
    var discount = Round2(subtotal * invoiceDiscountPct / 100m);
    var taxable  = subtotal - discount;
    var tax      = Round2(taxable * taxPct / 100m);
    return new InvoiceTotals(subtotal, discount, tax, taxable + tax);
}

private static decimal Round2(decimal v)
    => Math.Round(v, 2, MidpointRounding.AwayFromZero);

Prototype equivalents: lineAmt(), invTotals(), priceSub(), buildLines(), setupDue(), markSetupBilled(). See Appendix A for the full map.

7. Screens

Every screen below exists in the prototype. For each: what it is, the fields with validation, every action wired to an API and the tables it touches, acceptance criteria, and the React components to build.

Screen index

S1 · Accounts

What it is. The customer master list and the entry point to everything else. Four KPI tiles, a search/stage filter, and a table where every row summarises the commercial state of one account.

Fields (filter bar)

Columns: Account (name + country + legal name) · Stage pill · Owner · Apps count · APIs count · Cloud providers · Monthly recurring · Open balance · Last activity · Open button.

Actions

Acceptance criteria

API

GET /api/v1/customers?q=&stage=&owner=&hasBalance=&page=&size=&sort=
  → { items:[{ customerId, code, displayName, legalName, countryCode, stage, status,
               ownerName, appCount, apiCount, cloudProviders:[], mrr, openBalance,
               lastActivity:{type,date} }], total, page, size }

Components AccountsPage → KpiTile × 4, AccountFilterBar, AccountTable, StagePill, MoneyCell

Tables customer R · subscription_item R · catalog_item R · invoice R · customer_activity R · cloud_account R

S2 · Account · Overview

What it is. The commercial summary of one customer: four KPI tiles, the account facts panel, and a "next steps" panel that surfaces open follow-ups, pending requests and — critically — unbilled setup fees.

Fields (Account panel, read-only here; edited in the modal)

Registered entity · Country · Website · Stage · Account owner · Source · Tax registration · Customer since · Billing cycle · Standard discount % · Cloud (managed/self).

KPI tiles

Actions

Acceptance criteria

API

GET   /api/v1/customers/{id}                  → account + KPIs + setupDue breakdown
PATCH /api/v1/customers/{id}                  { displayName, legalName, ... , rowVersion }
GET   /api/v1/customers/{id}/charges/preview?period=2026-09
POST  /api/v1/customers/{id}/activities
POST  /api/v1/activities/{activityId}/complete
POST  /api/v1/customers/{id}/suspend          { reason }

Components AccountOverviewTab → KpiTile, AccountFactsPanel, NextStepsPanel, SetupFeeWarning ★, EditAccountModal, LogActivityModal

Tables customer RW · subscription_item R · cloud_cost_period R · tx_usage_period R · invoice R · change_request R · customer_activity RW · audit_log A

S3 · Account · Contacts

What it is. The people at this customer. One is primary; one or more receive invoices.

Fields (add/edit modal)

Actions

Acceptance criteria

Tables customer_contact RW · outbox_message W · audit_log A

S4 · Account · Meetings & notes

What it is. The CRM timeline for one account: meetings, calls, notes and emails, newest first, with follow-ups that surface on S2 and S8.

Fields (Log activity modal)

Actions

Acceptance criteria

Tables customer_activity RW · activity_attendee RW

S5 · Account · Apps & APIs ★ high value

What it is. The subscription editor. Two groups — Apps and External APIs — each item showing list prices, the setup fee, a term toggle and a negotiated price box. For API items it also renders a live usage meter. The right rail totals the change and, when something new has been switched on, shows the unbilled setup fee with a link to raise it.

Fields, per catalog item row

Right rail

Apps monthly · Apps annual terms · APIs monthly · APIs annual terms · API overage to date · Recurring per month · Setup fees not yet billed · warning + "raise it now" link · Save.

Actions

Acceptance criteria

API

GET    /api/v1/customers/{id}/subscription
POST   /api/v1/customers/{id}/subscription/items
PATCH  /api/v1/subscription/items/{itemId}
DELETE /api/v1/subscription/items/{itemId}
POST   /api/v1/subscription/items/{itemId}/waive-setup
GET    /api/v1/customers/{id}/usage?period=2026-09

Components SubscriptionEditor ★ → CatalogGroupSection, CatalogItemRow, TermToggle, PriceOverrideInput, SetupStatePill ★, UsageMeter, ChargeSummaryRail ★

Tables catalog_item R · subscription_item RW · subscription_item_change A · api_usage_period RW · audit_log A

S6 · Account · Cloud

What it is. The cloud accounts we operate for this customer, their provider cost for the period, the management markup, and the rebilled figure.

Fields (cloud account modal)

Actions

Acceptance criteria

Tables cloud_account RW · cloud_cost_period RW · customer W · audit_log A

S7 · Account · Billing

What it is. Every invoice for this account with its type, period, due date, total, status and ageing bucket.

Columns Invoice · Type · Period · Due · Total · Status · Age · Open.

Actions

Acceptance criteria

Tables invoice R · invoice_line R · payment R

S8 · Meetings & notes (global)

What it is. Every conversation across the whole book, newest first, filterable. This is how a manager sees what the team did this week and what is still open.

Filters Everything · Open follow-ups · Meetings · Calls · Notes. Plus owner and date-range in the query string.

Actions

Acceptance criteria

Tables customer_activity R · customer R

S9 · Onboarding wizard (5 steps)

What it is. The single path that creates everything a new customer needs, ending in an editable first invoice. Five steps with a running total rail: Company → Contact → Apps & APIs → Cloud & fees → Review.

S9.1 Company

S9.2 Contact

Name · Role · Email for invoices (required) · Phone · Opening CRM note (free text, becomes the first customer_activity).

S9.3 Apps & APIs

The same picker as S5, grouped Apps / External APIs, with per-item term radio and price override. Nothing is pre-selected except items flagged is_core.

S9.4 Cloud & fees

S9.5 Review

Read-only summary of all four steps plus the running total: Apps monthly · APIs monthly · Annual terms · Cloud rebilled · Transaction fees · Discount · Per month · One-time setup · First invoice.

Actions

Acceptance criteria

API

POST /api/v1/customers/onboard
{
  company:{ displayName, legalName, countryCode, website, ownerUserId, source, stage,
            taxRegistration, standardDiscountPct, billingCycle, startDate, isPilot },
  contact:{ fullName, jobTitle, email, phone, openingNote },
  items:[ { catalogItemId, term, unitPrice? } ],
  cloud:{ managed, provider, accountRef, region, expectedMonthlyCost, markupPct } | null,
  txFees:[ { txFeeRateId, expectedQuantity } ]
}
→ 201 { customerId, code, subscriptionId, draftInvoiceId | null }

Components OnboardWizard → StepBar, CompanyStep, ContactStep, CatalogStep (reuses CatalogItemRow), CloudAndFeesStep, ReviewStep, RunningTotalRail ★

Tables as listed in the Create action above.

S10 · Dashboard

What it is. The provider's commercial overview: four KPI tiles, two action banners (unbilled setup fees, pending requests), and revenue by account split across the four streams.

KPI tiles

Banners

Revenue by account table Account · Stage · Apps · APIs · Overage · Cloud · Transactions · Run rate.

Actions

Acceptance criteria

Tables listed above, all R except the run action.

S11 · Subscriptions

What it is. Every subscribed line across the whole book, one row per subscription_item. This is the report finance uses to answer "what are we actually billing for?".

Columns Account · Item · Category (App/API pill) · Group · Term · Since · Price · Monthly equivalent · Setup fee · Setup status · Pricing (list/override).

Filters account, category, term, setup status (Due/Billed/Waived), pricing (list/override).

Actions

Acceptance criteria

Tables subscription_item R · catalog_item R · customer R

S12 · Requests ★ high value

What it is. The approval queue. A customer asked for an app or API from their portal; approving it adds the item to their subscription dated today and queues the setup fee.

Columns Request code · Account + requester · Item + category pill · Term · Asked on · Why (justification) · Price · Setup fee · Status · Approve/Decline.

Actions

Acceptance criteria

API

GET  /api/v1/requests?status=Pending&page=&size=
POST /api/v1/requests/{id}/approve   { effectiveFrom?, unitPrice?, note? }  → 200 { subscriptionItemId }
POST /api/v1/requests/{id}/decline   { reason }                             → 200

Components RequestQueue → RequestRow, ApproveDialog ★ (shows quoted vs current price, effective date, setup fee), DeclineDialog

Tables change_request RW · subscription_item W · subscription_item_change A · api_usage_period W · customer_activity W · catalog_item R · audit_log A · outbox_message W

S13 · Cloud accounts

What it is. Every managed cloud account across all customers, with period costs, markups, rebilled amounts and margin. Three KPI tiles: provider cost, rebilled, management margin.

Columns Account (customer) · Provider pill · Reference · Region · Cost · Markup % · Rebilled · Note · Edit.

Actions

Acceptance criteria

Tables cloud_account RW · cloud_cost_period RW · customer R · audit_log A

S14 · Transaction fees

What it is. Two tables. Metered volumes — what each customer consumed this period, with cost, billable and margin. Fee rate card — the master list of per-event charges with our cost and the customer price.

Fields (rate card row)

Actions

Acceptance criteria

Tables tx_fee_rate RW · customer_tx_fee_rate RW · tx_usage_period RW · customer R · audit_log A

S15 · Marketplace

What it is. The master catalog, tabbed Everything / Apps / External APIs, grouped into the two groups. Apps show setup, monthly, annual and subscriber count. APIs additionally show included calls and overage rate.

Columns Item (name + description) · Category pill · Setup · Monthly · Annual (+ % off) · Included · Overage · Subscribers · Edit.

Actions

Acceptance criteria

Tables catalog_item RW · catalog_item_price_history A · subscription_item R

S16 · Catalog item editor

What it is. The modal behind Add/Edit on S15. Category drives which fields are shown.

Fields

Acceptance criteria

Tables catalog_item RW · catalog_item_price_history A

S17 · Invoice builder ★★ the highest-value screen in the system

What it is. Where a human turns computed charges into an invoice they are willing to send. The lines are drafted from the subscription, closed cloud periods, closed usage periods and unbilled setup fees — and then every field is editable: description, quantity, rate, a per-line discount, the invoice-level discount, the dates, the printed note. Nothing is billed until Raise.

Header fields

Line table — every cell editable

Totals rail Account · Covers · Subtotal · Invoice discount − · Tax · Total · Save as draft · Raise invoice.

Actions

Acceptance criteria

API

POST /api/v1/invoices/draft-preview   { customerId, type, period }      → { lines:[], warnings:[] }
POST /api/v1/invoices                 { customerId, type, period, issueDate, dueDate,
                                        discountPct, discountReason, notes, internalNote, lines:[] }
                                                                        → 201 { invoiceId, status:'Draft' }
PUT  /api/v1/invoices/{id}            (same body; Draft only)           → 200
POST /api/v1/invoices/{id}/raise      Idempotency-Key required          → 200 { invoiceNumber, status:'Issued' }
POST /api/v1/invoices/{id}/void       { reason }                        → 200

Components InvoiceBuilder ★★ → InvoiceHeaderForm, EditableLineTable ★, LineRow, TotalsRail ★, SetupFeeBanner ★, RaiseConfirmDialog

Tables read: customer, customer_contact, subscription_item, catalog_item, api_usage_period, cloud_cost_period, tx_usage_period, billing_settings · write on save: invoice, invoice_line, invoice_status_history · write on raise: additionally subscription_item, the three period tables, number_sequence, outbox_message, audit_log

Why this screen carries the most risk. It is the only place where computed billing meets human judgement. Every rule in §6 is visible here, and every mistake here is visible to the customer. Build the resolver first, test it with golden files (§13.3), and only then wire the UI.

S18 · Invoices

What it is. Every invoice with status tabs and a "covers" filter. Drafts carry an Edit action; nothing else does.

Tabs All · Draft · Issued · Pending verification · Paid · Overdue · Void. Covers filter Everything · Combined · Apps & APIs · Cloud · Transactions.

Columns Invoice · Account · Covers · Period · Due · Discount · Total · Status · Edit/Open.

Actions

Acceptance criteria

Tables invoice R · customer R

S19 · Invoice document

What it is. The printable tax invoice: company block, bill-to snapshot, lines grouped by category, totals, payment instructions, and the payment record once settled.

Sections Header (type, number, dates, period, covers, currency) · Billed to (snapshot) · Reference (account code, owner, billing cycle) · Lines grouped by category · Totals · Printed note · Payment instructions or settlement record.

Actions

Acceptance criteria

Tables invoice R · invoice_line R · payment R · billing_settings R · bank_account R · crypto_wallet R

S20 / S29 · Payment ★ shared by console and portal

What it is. Where the amount due is turned into a transfer. Two methods, each with everything needed to pay and a place to declare what was sent.

Bank transfer fields (read-only, copyable) Beneficiary · Bank + branch · Account number · IBAN · SWIFT/BIC · Payment reference = invoice number.

Crypto fields Asset/network selector (USDT-ERC20, USDT-TRC20, USDC-Polygon, BTC) · Amount in asset (from locked quote) · Address + QR · Confirmations required · Rate lock countdown.

Confirmation fields

Actions

Acceptance criteria

Tables invoice RW · payment W · crypto_quote W · bank_account R · crypto_wallet R · invoice_status_history A · outbox_message W

S21 · Payments & proofs

What it is. The reconciliation queue. Submitted proofs wait here until a human matches them to a bank statement or a chain explorer and confirms.

Waiting table Invoice · Account · Amount · Method pill · Reference/hash · Not found / Confirm. History table Invoice · Account · Date · Method · Reference · Amount · Status.

Actions

Acceptance criteria

Tables payment RW · invoice RW · invoice_status_history A · audit_log A · outbox_message W

S22 · Accounts receivable

What it is. What is owed, how old it is, and who to chase. Four ageing tiles, ageing by account, and the open-invoice list sorted oldest first.

Buckets Current (not yet due) · 1–30 days · 31–60 days · 60+ days, computed from due_date vs today.

Columns (by account) Account · Owner · Invoice count · Current · 1–30 · 31–60 · 60+ · Total · Statement. Columns (open invoices) Invoice · Account · Covers · Due · Age · Bucket · Amount · Status · Remind / Mark paid.

Actions

Acceptance criteria

Tables invoice R · payment R · customer R · dunning_event W · credit_note W

S23 · Settings

What it is. Invoice identity, tax and collections policy, the bank accounts and the crypto wallets shown to customers.

Fields

Actions

Acceptance criteria

Tables billing_settings RW · bank_account RW · crypto_wallet RW · audit_log A

S24 · Portal · Overview

What it is. What the customer sees first: their recurring cost, cloud and transaction charges for the period, anything outstanding, a heads-up about a queued setup fee, their subscription list and their API meters.

Tiles Recurring (per month) · Cloud this period · Transaction fees · Amount due.

Banners open invoice with Pay now · pending requests · queued setup fee naming the items.

Acceptance criteria

API GET /api/v1/portal/me/overview Tables customer R · subscription_item R · catalog_item R · api_usage_period R · cloud_cost_period R (rebill only) · tx_usage_period R (bill only) · invoice R · change_request R

S25 · Portal · Apps & APIs

What it is. The marketplace as the customer sees it: everything listed, ticks on what they have, prices on everything, and a Request button on what they do not. Terms are visible but not editable — only a request can change a subscription.

Request modal fields

Actions

Acceptance criteria

Tables catalog_item R · subscription_item R · change_request RW · api_usage_period R

S26 · Portal · My requests

What it is. What they asked for and where each request stands.

Columns Request · Item + category · Term · Asked · Reason · Price · Setup fee · Status (+ "Live since " when approved).

Acceptance criteria

Tables change_request R · catalog_item R

S27 · Portal · Cloud & transactions

What it is. The pass-through charges for the period, so the customer can see what is coming before the invoice arrives.

Cloud table Provider · Account · Region · Rebilled amount · period. Transaction table Fee · Provider · Volume · Unit price · Amount.

Acceptance criteria

Tables cloud_cost_period R (rebill only) · cloud_account R (provider, ref, region only) · tx_usage_period R (qty, price, bill only) · tx_fee_rate R (name, vendor, unit only)

S28 · Portal · Invoices & payments

What it is. Their invoice history and the way to pay. Drafts never appear.

Columns Invoice · Covers · Period · Due · Total · Status · Pay/View.

Acceptance criteria

Tables invoice R · payment R

8. API reference

8.1 Conventions

• Base path /api/v1. Bearer token required on every route.
• Tenant comes from the token, never from a route or body parameter. Portal tokens carry customer_id; console tokens carry staff roles.
• Every mutating endpoint requires an Idempotency-Key header. Replays return the original response.
• Money in JSON is a string decimal ("1234.56"), never a float.
• Dates are ISO-8601; periods are "2026-09".
• Concurrency: If-Match with the base64 rowVersion on PATCH/PUT of aggregates. Mismatch → 409.
• Pagination: ?page=1&size=50, response { items, total, page, size }.

8.2 Endpoint list

# ── CRM ───────────────────────────────────────────────────
GET    /customers                              ?q&stage&owner&hasBalance&page&size&sort
POST   /customers                              (bare create; prefer /onboard)
GET    /customers/{id}
PATCH  /customers/{id}
POST   /customers/{id}/suspend                 { reason }
POST   /customers/onboard                      (the wizard, one transaction)
GET    /customers/{id}/contacts
POST   /customers/{id}/contacts
PATCH  /contacts/{contactId}
POST   /contacts/{contactId}/make-primary
POST   /contacts/{contactId}/invite
DELETE /contacts/{contactId}
GET    /activities                             ?type&owner&from&to&openOnly
POST   /customers/{id}/activities
PATCH  /activities/{id}
POST   /activities/{id}/complete

# ── Catalog ───────────────────────────────────────────────
GET    /catalog-items                          ?kind&listed&sellable
POST   /catalog-items
PATCH  /catalog-items/{id}
GET    /catalog-items/{id}/price-history

# ── Subscription ──────────────────────────────────────────
GET    /customers/{id}/subscription
POST   /customers/{id}/subscription/items      { catalogItemId, term, unitPrice?, effectiveFrom }
PATCH  /subscription/items/{itemId}            { term?, unitPrice?, reason? }
DELETE /subscription/items/{itemId}            { effectiveTo, reason }
POST   /subscription/items/{itemId}/waive-setup{ reason }
GET    /subscription-items                     ?customerId&kind&term&setupState&pricing

# ── Requests ──────────────────────────────────────────────
GET    /requests                               ?status
POST   /requests/{id}/approve                  { effectiveFrom?, unitPrice?, note? }
POST   /requests/{id}/decline                  { reason }
POST   /portal/requests                        { catalogItemId, term, justification }
POST   /portal/requests/{id}/cancel

# ── Metering ──────────────────────────────────────────────
POST   /usage/api/ingest                       (gateway → daily counters, batch)
GET    /customers/{id}/usage                   ?period
POST   /usage/{period}/close
PUT    /cloud-accounts/{id}/periods/{period}   { providerCost, evidenceUrl? }
POST   /cloud-costs/import                     (CSV)
POST   /cloud-costs/{period}/close
PUT    /tx-usage/{customerId}/{rateId}/{period}{ quantity }
POST   /tx-usage/import                        (CSV)
POST   /tx-usage/{period}/close
GET    /tx-fee-rates
PATCH  /tx-fee-rates/{id}
PUT    /customers/{id}/tx-fee-rates/{rateId}   { unitPrice, effectiveFrom }

# ── Cloud ─────────────────────────────────────────────────
GET    /cloud-accounts                         ?customerId&provider
POST   /customers/{id}/cloud-accounts
PATCH  /cloud-accounts/{id}
DELETE /cloud-accounts/{id}

# ── Invoicing ─────────────────────────────────────────────
POST   /invoices/draft-preview                 { customerId, type, period }   ← writes nothing
GET    /invoices                               ?status&type&customerId&period
POST   /invoices                               (save draft)
GET    /invoices/{id}
PUT    /invoices/{id}                          (Draft only)
POST   /invoices/{id}/raise                    ← the transaction that matters
POST   /invoices/raise-batch                   { invoiceIds:[] }
POST   /invoices/{id}/void                     { reason }
GET    /invoices/{id}/pdf
POST   /billing/runs                           { period, dryRun }

# ── Payments ──────────────────────────────────────────────
POST   /invoices/{id}/crypto-quote             { walletId }
POST   /invoices/{id}/payments                 { method, amountClaimed, wireReference|txHash, ... }
GET    /payments                               ?state
POST   /payments/{id}/verify                   { amountVerified }
POST   /payments/{id}/reject                   { reason }

# ── Collections ───────────────────────────────────────────
GET    /receivables/ageing                     ?asOf
POST   /customers/{id}/statement
POST   /invoices/{id}/remind
POST   /collections/dunning/run
POST   /invoices/{id}/write-off                { reason }

# ── Settings ──────────────────────────────────────────────
GET    /settings/billing
PATCH  /settings/billing
GET    /settings/bank-accounts
POST   /settings/bank-accounts
PATCH  /settings/bank-accounts/{id}
GET    /settings/wallets
POST   /settings/wallets
PATCH  /settings/wallets/{id}

# ── Portal (customer token) ───────────────────────────────
GET    /portal/me/overview
GET    /portal/me/subscription
GET    /portal/me/catalog
GET    /portal/me/usage                        ?period
GET    /portal/me/cloud-and-fees               ?period
GET    /portal/me/invoices
GET    /portal/me/invoices/{id}

8.3 Key payloads

POST /invoices/draft-preview

// request
{ "customerId": "…", "type": "Combined", "period": "2026-09" }

// response
{
  "lines": [
    { "category":"Apps",  "description":"Core & wallets (monthly)", "quantity":"1",
      "unitPrice":"1800.00", "lineDiscountPct":"0", "amount":"1800.00",
      "sourceKind":"SubscriptionItem", "sourceId":"…", "isProrated":false },
    { "category":"Setup", "description":"Cards — one-time setup fee", "quantity":"1",
      "unitPrice":"6000.00", "lineDiscountPct":"0", "amount":"6000.00",
      "sourceKind":"SetupFee", "sourceId":"<subscriptionItemId>", "isProrated":false },
    { "category":"Overage","description":"Payments API overage — 18,400 calls","quantity":"18.4",
      "unitPrice":"1.600000","lineDiscountPct":"0","amount":"29.44",
      "sourceKind":"ApiOverage","sourceId":"…","periodFrom":"2026-08-01","periodTo":"2026-08-31" },
    { "category":"Cloud", "description":"AWS 4471-9982-1130 — Aug 2026 usage incl. 12% management",
      "quantity":"1","unitPrice":"5399.02","lineDiscountPct":"0","amount":"5399.02",
      "sourceKind":"CloudPeriod","sourceId":"…" }
  ],
  "warnings": [ "Transaction period 2026-08 for Sumsub — AML screening is still Open and was not included." ]
}

POST /invoices/{id}/raise → 200

{ "invoiceId":"…", "invoiceNumber":"INV-2026-0007", "status":"Issued",
  "issueDate":"2026-09-10", "dueDate":"2026-09-24",
  "total":"25095.00",
  "setupFeesMarkedBilled":[ { "subscriptionItemId":"…", "itemName":"Cards", "amount":"6000.00" } ],
  "periodsMarkedBilled":{ "api":2, "cloud":1, "transactions":3 } }

POST /requests/{id}/approve → 200

{ "requestId":"…", "status":"Approved",
  "subscriptionItemId":"…", "effectiveFrom":"2026-09-11",
  "unitPrice":"1200.00", "term":"Monthly",
  "setupFee":{ "amount":"1500.00", "state":"Due",
               "note":"Will appear on the next invoice as 'Wallets API — one-time setup fee'" },
  "firstInvoiceEstimate":{ "prorated":"760.00", "periodFrom":"2026-09-11","periodTo":"2026-09-30" } }

8.4 Error contract

{ "type":"https://errors.ledgerline.io/invoice-not-draft",
  "title":"Invoice cannot be edited",
  "status":409,
  "code":"INVOICE_NOT_DRAFT",
  "detail":"INV-2026-0005 was issued on 2026-09-01. Void it and raise a new invoice.",
  "instance":"/api/v1/invoices/…",
  "traceId":"00-…" }

9. .NET backend structure

9.1 The central architectural decision

Billing calculation is pure. It takes a snapshot of state and produces a charge set. It touches no database, no clock, no configuration. Everything that reads or writes is a thin shell around it.

This is not architectural taste. It is the only way to make month-end reproducible: you can replay September's inputs in 2029 and get September's invoice, byte for byte.

Input snapshot ──▶ ChargeResolver (pure) ──▶ ChargeSet ──▶ InvoiceDraftBuilder ──▶ Invoice (Draft)
                                                                                        │
                                                                        human edits ────┤
                                                                                        ▼
                                                                              RaiseInvoiceHandler
                                                                              (one transaction)

9.2 Project layout

src/
  Ledgerline.Domain/                 ← no dependencies. Ever.
    Customers/          Customer.cs, CustomerContact.cs, CustomerActivity.cs
    Catalog/            CatalogItem.cs, CatalogKind.cs, BillingTerm.cs
    Subscriptions/      Subscription.cs, SubscriptionItem.cs, SetupState.cs
                        SubscriptionItem.MarkSetupBilled(), .ChangeTerm(), .Override()
    Requests/           ChangeRequest.cs  (Approve/Decline are methods on the aggregate)
    Billing/
      ChargeResolver.cs      ← pure, the heart of §6
      Proration.cs
      Money.cs               ← Round2, all arithmetic
      InvoiceTotals.cs
    Invoicing/          Invoice.cs, InvoiceLine.cs
                        Invoice.AddLine(), .Recalculate(), .Raise(), .Void()
    Payments/           Payment.cs, CryptoQuote.cs
    Metering/           ApiUsagePeriod.cs, CloudCostPeriod.cs, TxUsagePeriod.cs

  Ledgerline.Application/            ← use cases, MediatR handlers, DTOs, validators
    Invoicing/Commands/  SaveDraftInvoice, RaiseInvoice, VoidInvoice
    Invoicing/Queries/   DraftPreview, GetInvoice, ListInvoices
    Requests/Commands/   ApproveRequest, DeclineRequest
    Billing/             RunBillingForPeriod
    Abstractions/        IChargeResolver, IInvoiceNumberGenerator, IClock, ICurrentUser

  Ledgerline.Infrastructure/
    Persistence/        LedgerlineDbContext, configurations, migrations, RLS setup
    Numbering/          InvoiceNumberGenerator (SELECT … FOR UPDATE on number_sequence)
    Pdf/                QuestPDF invoice renderer
    Email/              Templated sender reading notification_template
    Crypto/             RateProvider (quote locking)
    Outbox/             OutboxDispatcher

  Ledgerline.Api/
    Controllers/        one per resource group in §8.2
    Portal/             separate controllers, separate DTOs, separate policy
    Middleware/         IdempotencyMiddleware, TenantResolution, ProblemDetails

  Ledgerline.Workers/
    CloseUsagePeriodsWorker     (1st of month, 02:00 UTC)
    OverdueSweepWorker          (daily, 03:00 UTC)
    DunningWorker               (daily, 09:00 local per customer)
    OutboxDispatcherWorker      (every 10s)
    AnnualRenewalWorker         (daily — items where term_renews_on = today)

tests/
  Ledgerline.Domain.Tests/            ← the golden files live here
  Ledgerline.Application.Tests/
  Ledgerline.Api.IntegrationTests/    ← Testcontainers, real Postgres
  Ledgerline.Architecture.Tests/

9.3 The raise transaction — the one that must be right

public async Task<RaiseResult> Handle(RaiseInvoice cmd, CancellationToken ct)
{
    await using var tx = await _db.Database.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct);

    var invoice = await _db.Invoices
        .Include(i => i.Lines)
        .SingleAsync(i => i.InvoiceId == cmd.InvoiceId, ct);

    // 1. Guards — each with its own error code (§8.4)
    if (invoice.Status != InvoiceStatus.Draft) throw new DomainException("INVOICE_NOT_DRAFT");
    if (invoice.Lines.Count == 0)              throw new DomainException("INVOICE_NO_LINES");
    await _guards.EnsureBillingContactAsync(invoice.CustomerId, ct);
    await _guards.EnsureReferencedPeriodsClosedAsync(invoice, ct);
    _authority.EnsureDiscountAllowed(invoice.DiscountPct);

    // 2. Number, dates, bill-to snapshot
    invoice.InvoiceNumber = await _numbers.NextAsync($"invoice:{_clock.UtcNow:yyyy}", ct);
    invoice.IssueDate     = _clock.Today;
    invoice.DueDate       = _clock.Today.AddDays(await _settings.TermsDaysAsync(invoice.CustomerId, ct));
    await _snapshots.ApplyBillToAsync(invoice, ct);

    // 3. Freeze totals
    invoice.Recalculate();

    // 4. Consume what this invoice bills — order matters for readable failures
    await _setup.MarkSetupBilledAsync(invoice, ct);            // §6.4
    await _periods.MarkPeriodsBilledAsync(invoice, ct);        // api / cloud / tx → Billed

    // 5. Transition + audit + side effects via outbox
    invoice.Transition(InvoiceStatus.Issued, _user.Id, reason: null);
    _db.OutboxMessages.Add(OutboxMessage.InvoiceRaised(invoice));
    _audit.Record("Invoice", invoice.InvoiceId, "Raised", before: null, after: invoice.Snapshot());

    await _db.SaveChangesAsync(ct);
    await tx.CommitAsync(ct);
    return RaiseResult.From(invoice);
}

Four things that must be true of this method

1. Everything is in one transaction. A crash after numbering but before marking setup billed would bill the fee twice next month.
2. The PDF and the email are not generated inline. They go through the outbox; a failing SMTP server must not roll back an invoice.
3. MarkSetupBilledAsync matches on source_id, never on description text.
4. Recalculate() runs after all edits and before the status change, so stored totals always match the stored lines.

9.4 Concurrency

• Two operators raising the same draft: second gets 409 CONCURRENCY_CONFLICT from the row_version token.
• Two operators approving the same request: the partial unique index ux_subitem_active rejects the duplicate subscription item; catch UniqueViolation and map to ITEM_ALREADY_SUBSCRIBED.
• Invoice numbering: SELECT next_value FROM number_sequence WHERE sequence_key = $1 FOR UPDATE. Never MAX(invoice_number) + 1.
• Crypto payment submitted twice: ux_payment_txhash rejects the second.

10. React frontend structure

10.1 Folder layout

src/
  app/            router, query client, auth, theme tokens
  api/            generated client (see 10.2), hooks per resource
  components/
    money/        MoneyCell, MoneyInput      ← decimal strings, never floats
    pills/        StatusPill, KindPill, TermPill, SetupStatePill ★
    data/         DataTable, KpiTile, AgeingBar, UsageMeter
    forms/        Field, Select, DateField, PercentInput
  features/
    accounts/     AccountsPage, AccountDetail(tabs), EditAccountModal
    activities/   Timeline, LogActivityModal
    subscription/ SubscriptionEditor ★, CatalogItemRow, ChargeSummaryRail ★
    onboarding/   OnboardWizard (5 steps), RunningTotalRail
    requests/     RequestQueue, ApproveDialog ★
    catalog/      MarketplacePage, CatalogItemEditor
    cloud/        CloudAccountsPage, CloudAccountModal
    txfees/       TxFeesPage, RateCardTable
    invoicing/    InvoiceBuilder ★★, EditableLineTable ★, TotalsRail ★,
                  InvoiceList, InvoiceDocument
    payments/     PaymentPage (shared), PaymentQueue
    receivables/  AgeingPage, StatementDialog
    settings/     SettingsPage
    portal/       Overview, Catalog, Requests, CloudAndFees, Invoices

10.2 Types are generated, never hand-written

// package.json
"scripts": {
  "api:types": "openapi-typescript http://localhost:5080/swagger/v1/swagger.json -o src/api/schema.d.ts"
}

Run it in CI. A drift between the C# DTO and the TS type must break the build, not production.

10.3 The three components to build once and reuse

10.4 Data layer rules

1. Money is a string end to end. MoneyInput parses on blur, stores a decimal string. Never parseFloat.
2. TanStack Query with staleTime: 0 for anything billing-related. A cached invoice total is a wrong invoice total.
3. Mutations invalidate by tag: raising an invoice invalidates invoices, receivables, dashboard, customer:{id}.
4. The invoice builder holds line state locally and posts the whole line set. No per-line PATCH endpoints — partial saves create half-invoices.
5. Optimistic updates are allowed for CRM (activities, contacts) and forbidden for anything that moves money.

10.5 Frontend rules that are not negotiable

• Never compute an invoice total in the browser for display after save — read the server's stored totals. The browser computes only while drafting.
• Never render a value the API did not send. If margin is absent, there is no margin UI.
• Every destructive action (void, write-off, remove item, decline request) uses a typed confirmation, not a bare confirm().
• Currency symbol and decimals come from the response, not from a hardcoded $.

11. State machines

11.1 Invoice

        create draft
            │
            ▼
       ┌─────────┐  raise   ┌──────────┐  payment submitted ┌──────────────────────┐
       │  Draft  │─────────▶│  Issued  │───────────────────▶│ PendingVerification  │
       └─────────┘          └──────────┘                    └──────────────────────┘
            │                    │  ▲                            │            │
            │ void               │  │ due date passes            │ verified   │ rejected
            │                    ▼  │                            ▼            │
            │               ┌──────────┐                     ┌───────┐        │
            └──────────────▶│ Overdue  │────────────────────▶│ Paid  │◀───────┘
                     void   └──────────┘     verified        └───────┘
                                 │
                                 │ void (finance only, reason required)
                                 ▼
                            ┌────────┐
                            │  Void  │   terminal
                            └────────┘

11.2 Subscription item setup fee

Due → Billed (on raise) · Due → Waived (finance, reason) · Billed is terminal (DB trigger).

11.3 Change request

Pending → Approved (creates item, effective today) · Pending → Declined (reason) · Pending → Cancelled (by the customer).

11.4 Usage / cloud / transaction period

Open → Closed (worker or manual, monthly) · Closed → Billed (on raise). Only Closed is billable. Billed is terminal.

12. Notifications

Templates live in the database so wording changes are not deploys.

Rules: every email is sent through the outbox; a template renders with {{invoiceNumber}}, {{total}}, {{dueDate}}, {{customerName}}, {{portalLink}}; per-invoice dunning cooldown is 72 hours; nothing is sent for Draft invoices, ever.

13. Test matrix

13.1 Invariants — one test each, named after the rule

13.2 Concurrency (Testcontainers, real Postgres, no mocks)

13.3 Charge resolver — golden files

One JSON input snapshot and one expected ChargeSet per scenario, committed to the repo:

combined-full, apps-only, api-only-customer, cloud-only, transactions-only, first-invoice-with-setup, mid-period-addition-prorated, mid-period-removal-credit, annual-renewal, trial-no-invoice, overage-per-call, overage-per-1000, zero-usage, discount-stacking, customer-rate-override.

A change to any golden file requires a reviewer from finance. That is the point.

13.4 Architecture tests (CI, fail the build)

• No portal controller returns a type with a property named ProviderCost, UnitCost, CostAmount, Margin, MarkupPct or InternalNote.
• Ledgerline.Domain references no EF Core, no DateTime.Now, no HttpContext.
• Every enum persisted has a DB enum type; no string status columns.
• Every mutating controller action has [Idempotent].
• Every money property is decimal with [Precision(18,4)].

13.5 Security

• Portal token cannot read another customer's invoice (404, not 403).
• RLS is on for the portal connection string; a raw SQL query without a tenant filter returns zero rows.
• Impersonation is read-only unless explicitly elevated, and always audited.
• Wallet address change requires a second approver.

14. Delivery plan

The first useful slice is phases 0–3: onboard manually, subscribe apps, raise one invoice. About six weeks.

15. Failure modes — read before writing code

Non-functional targets

Alert on these

• Any Billed → Due attempt (should be impossible; if it fires, something bypassed EF).
• Invoice-number gap detected by the nightly integrity job.
• A period still Open on the 5th of the following month.
• Payment in Submitted for more than 3 business days.
• Outbox message with attempts > 5.
• Any portal response containing a cost-shaped field (runtime canary, in addition to the build-time test).

16. Decisions needed before build

17. Generation guide

Feed these to the coding assistant in order. Each step compiles and tests green before the next.

Step 1 — Domain

Create Ledgerline.Domain targeting net8.0 with no package references. Implement the entities in §5.2 as C# classes with private setters and behaviour methods: SubscriptionItem.MarkSetupBilled(Guid invoiceId), .Waive(string reason), .ChangeTerm(BillingTerm, decimal listPrice), .EndOn(DateOnly); Invoice.AddLine(...), .Recalculate(), .Raise(string number, DateOnly issue, DateOnly due), .Void(string reason); ChangeRequest.Approve(DateOnly effectiveFrom, decimal price), .Decline(string reason). Implement Money.Round2 using MidpointRounding.AwayFromZero. Throw DomainException with the codes from §8.4. No DB, no clock, no IO.

Step 2 — Charge resolver

Implement ChargeResolver per §6.2–§6.8 as a pure function over an input snapshot record. Cover: monthly and annual apps, API tier fees, per-item setup fees for items in Due, closed API overage (both bases), closed cloud periods with snapshot markup, closed transaction periods, proration on first and last period, invoice-type filtering. Return warnings for open periods. Add the 15 golden-file tests in §13.3.

Step 3 — Persistence

Create LedgerlineDbContext with EF Core 8 and Npgsql. Map every table from §5.2 including Postgres enums, partial unique indexes, CHECK constraints and the four triggers from §5.3 in a migration. Add RLS policies for the portal role. Configure [Precision(18,4)] on all money.

Step 4 — Invoicing use cases

Implement DraftPreview, SaveDraftInvoice, RaiseInvoice, VoidInvoice as MediatR handlers. RaiseInvoice must follow §9.3 exactly: guards, numbering via FOR UPDATE, bill-to snapshot, recalculate, MarkSetupBilledAsync, MarkPeriodsBilledAsync, transition, outbox, audit, one transaction. Write the concurrency tests from §13.2 against Testcontainers Postgres.

Step 5 — Requests

Implement ApproveRequest and DeclineRequest. Approval creates a SubscriptionItem with effective_from defaulting to today and setup_state = Due, writes a customer_activity row, and returns the prorated first-invoice estimate. Enforce AC-12.1 through AC-12.7.

Step 6 — API surface

Scaffold controllers for §8.2 with ProblemDetails, idempotency middleware, tenant resolution from the token, and separate portal controllers with separate DTOs. Add the architecture tests from §13.4.

Step 7 — Workers

Implement CloseUsagePeriodsWorker, OverdueSweepWorker, DunningWorker, OutboxDispatcherWorker, AnnualRenewalWorker with Hangfire. All idempotent, all safe to run twice.

Step 8 — Shared React components

Build MoneyCell/MoneyInput (decimal strings only), StatusPill, SetupStatePill, CatalogItemRow with a mode prop (edit | select | request), UsageMeter, DataTable. Generate types from the OpenAPI document.

Step 9 — Invoice builder

Build S17 per §7: header form, EditableLineTable with live per-line amounts, totals rail, setup-fee banner, save-draft and raise actions. All 14 acceptance criteria. Line state is local; the whole set posts on save.

Step 10 — Remaining screens

Build in this order: S1–S4 (CRM), S5 (subscription editor), S15/S16 (catalog), S18/S19 (invoices), S20/S21 (payments), S22 (AR), S12 (requests), S13/S14 (cloud, fees), S24–S28 (portal), S9 (wizard last — it composes the others).

Prompt suffix — paste with every step

Constraints: money is decimal with precision 18,4 in C# and a decimal string in JSON — never double, never parseFloat. The setup fee is per subscription_item and is marked Billed only inside the raise transaction. An invoice that is not Draft is immutable. Cost and margin fields must never appear in a portal DTO. Every mutating endpoint is idempotent. Rounding is half-away-from-zero at each step of §6.8, not once at the end. Write the test before the implementation where a rule in §13.1 applies.

18. Reference tables

Three small platform-owned tables that §8 exposes but §5 did not define. Seeded once per environment, identical for every customer, never edited by a customer.

-- Notification copy, so wording changes are not deploys.
CREATE TABLE notification_template (
    template_key  text NOT NULL,
    channel       text NOT NULL,             -- 'Email','InApp','Portal'
    language_code text NOT NULL DEFAULT 'en',
    subject       text NULL,
    body          text NOT NULL,             -- {{invoiceNumber}} {{total}} {{dueDate}} {{portalLink}}
    PRIMARY KEY (template_key, channel, language_code)
);

-- Named reasons, so "why was this discounted" is analysable rather than free text.
CREATE TABLE discount_reason (
    reason_code   text PRIMARY KEY,          -- 'MIGRATION','COMPETITIVE','GOODWILL','VOLUME','PILOT'
    display_name  text NOT NULL,
    max_pct       numeric(5,2) NOT NULL,     -- ceiling for this reason
    requires_role text NOT NULL,             -- 'BillingOperator' | 'FinanceAdmin'
    is_active     bool NOT NULL DEFAULT true
);

-- Discount authority by role. Read by the Raise guard and by S17 to disable the button.
CREATE TABLE discount_authority (
    role_name  text PRIMARY KEY,             -- 'AccountOwner','BillingOperator','FinanceAdmin'
    max_pct    numeric(5,2) NOT NULL
);

discount_authority is a table rather than a constant because the ceiling is a commercial policy, and commercial policies change more often than code deploys.

19. API → table reference

R read · W write · A append-only.

19.1 CRM

19.2 Subscription

19.3 Requests

19.4 Invoicing — the important rows

19.5 Payments and collections

19.6 Workers

20. Seed data

20.1 Tier 1 — catalog (every environment, idempotent on code)

Apps — group_name = 'Apps', kind = 'App'

External APIs — group_name = 'External APIs', kind = 'Api'

Annual = round(monthly × 12 × 0.85). Banks API is deliberately PerCall so the per-call code path is always exercised by seed data.

20.2 Tier 1 — transaction fee rate card

20.3 Tier 1 — discount authority and reasons

Reasons: MIGRATION (25, BillingOperator) · COMPETITIVE (25, BillingOperator) · VOLUME (20, BillingOperator) · PILOT (100, FinanceAdmin) · GOODWILL (15, BillingOperator).

20.4 Tier 2 — company settings, banks, wallets

Company: Ledgerline Technologies FZ-LLC, Unit 704 Innovation Hub, Dubai Internet City, TRN 100482930500003. Tax VAT 5%. Terms 14 days. Late fee 1.5%/month. Dunning {3,7,14}. Suspend after 30.

Banks: Emirates NBD (primary USD, SWIFT EBILAEAD) · JPMorgan Chase NY (USD correspondent, SWIFT CHASUS33). Wallets: USDT/Ethereum (12 conf) · USDT/Tron (19) · USDC/Polygon (60) · BTC/Bitcoin (3).

20.5 Tier 3 — dev and QA seed (guard against production)

Five customers, chosen to exercise the edge cases rather than to look realistic.

public static class DevScenarios
{
    // GlobalBridge Sept 2026 → Combined invoice with every line category present
    public const string FullCombined = "GlobalBridge combined";

    // Add Cards to GlobalBridge AFTER their August invoice was raised.
    // The September draft MUST contain "Cards — one-time setup fee $6,000".
    // This is the regression fixture for the customer-level-flag bug.
    public const string SetupAfterFirstInvoice = "Add Cards post-invoice";

    // FastXe INV-2026-0006, due 2026-08-15 → 26 days overdue, bucket 1–30
    public const string Overdue = "FastXe overdue";

    // Paybitz cloud billed on its own invoice, apps on another, same period
    public const string SplitInvoices = "Paybitz split";

    // Rapidz: pilot, zero invoices, one open follow-up
    public const string TrialNoInvoice = "Rapidz pilot";

    // Approve a pending request dated 3 days ago → item effective TODAY, prorated
    public const string ApprovalStartsToday = "Approve GlobalBridge Exchange API";
}

20.6 Verification queries — run after seeding, in every environment

-- 1. No lifetime term survived anywhere. Must return 0.
SELECT count(*) FROM pg_enum e JOIN pg_type t ON t.oid = e.enumtypid
WHERE t.typname = 'billing_term' AND e.enumlabel ILIKE '%life%';

-- 2. Exactly two catalog groups. Must return 2, named Apps and External APIs.
SELECT DISTINCT group_name FROM catalog_item ORDER BY 1;

-- 3. Every API item has complete metering. Must return 0.
SELECT count(*) FROM catalog_item
WHERE kind = 'Api' AND (included_calls IS NULL OR overage_rate IS NULL OR overage_basis IS NULL);

-- 4. No setup fee is marked Billed without an invoice. Must return 0.
SELECT count(*) FROM subscription_item
WHERE setup_state = 'Billed' AND setup_billed_on_invoice_id IS NULL;

-- 5. No setup fee billed twice (same item on two invoices). Must return 0.
SELECT count(*) FROM (
  SELECT source_id FROM invoice_line l JOIN invoice i USING (invoice_id)
  WHERE l.source_kind = 'SetupFee' AND i.status <> 'Void'
  GROUP BY source_id HAVING count(*) > 1) d;

-- 6. No issued invoice without a number, date or due date. Must return 0.
SELECT count(*) FROM invoice
WHERE status <> 'Draft' AND (invoice_number IS NULL OR issue_date IS NULL OR due_date IS NULL);

-- 7. Stored totals match stored lines on every issued invoice. Must return 0.
SELECT count(*) FROM invoice i
WHERE i.status <> 'Draft'
  AND round(i.subtotal, 2) <> (SELECT round(coalesce(sum(amount), 0), 2)
                               FROM invoice_line WHERE invoice_id = i.invoice_id);

-- 8. No invoice line references an Open period. Must return 0.
SELECT count(*) FROM invoice_line l JOIN invoice i USING (invoice_id)
JOIN cloud_cost_period c ON c.cloud_cost_id = l.source_id
WHERE l.source_kind = 'CloudPeriod' AND i.status <> 'Draft' AND c.state = 'Open';

-- 9. Invoice numbers are gapless per year. Must return 0 gaps.
WITH n AS (SELECT substring(invoice_number from '\d{4}$')::int AS seq,
                  substring(invoice_number from 'INV-(\d{4})')::int AS yr
           FROM invoice WHERE invoice_number IS NOT NULL)
SELECT count(*) FROM (
  SELECT yr, seq, lag(seq) OVER (PARTITION BY yr ORDER BY seq) AS prev FROM n) g
WHERE prev IS NOT NULL AND seq <> prev + 1;

-- 10. Every customer with an issued invoice has a billing contact. Must return 0.
SELECT count(DISTINCT i.customer_id) FROM invoice i
WHERE i.status <> 'Draft' AND NOT EXISTS (
  SELECT 1 FROM customer_contact c
  WHERE c.customer_id = i.customer_id AND c.is_billing AND NOT c.is_archived);

Queries 4, 5 and 9 should also be automated tests, not just a checklist. Query 5 is the one that keeps "a setup fee is charged exactly once, per item" true after a future refactor.

Appendix A — Prototype to production map

The prototype is a single HTML file with in-memory state. Every symbol in it has a production equivalent.

Appendix B — Reading order for a new engineer

1. Open ledgerline-billing-prototype.html. Onboard a customer, add an app to an existing customer, raise their invoice, pay it, verify it. Twice.
2. This document: §6 (the billing engine) and §11 (state machines).
3. §6.4 again. The setup-fee lifecycle is the thing this system exists to get right.
4. §9 (backend) or §10 (frontend), depending on your role.
5. §15 (failure modes) before writing any code.
6. §13.1 — write the test before the feature for anything listed there.