Billing Layers

Billing gets confusing because it mixes:

• commercial flows (invoices, bank transfer)
• entitlement accounting (credits, reservations, revenue recognition)

Billing is designed in layers:

1. Catalog and Pricing (what we sell)
2. Commercial Documents (how customers buys)
3. Entitlements Engine (what customers can spend)
4. Reporting & Finance Exports (how we reconcile)

Overview

We group each table according to the different Billing Layers.

One aggregate root sits above the layers: billing_accounts — one row per Org::Company. The account owns its billing_agreements, and each agreement carries billing_agreement_terms.

1. Catalog & Pricing (what we sell)

Tables:

• billing_products
• billing_product_prices
• billing_legal_entities (Jod companies)

A Product defines what is being sold AND what it grants.

• "gig credits"
• "placement credits"

A ProductPrice defines how we sell the product in a specific market:

• currency (SGD, IDR, KRW, etc)
• price
• tax rules
• seller-of-record (which Jod entity is selling, i.e. billing_legal_entities)
• gig platform fee rate terms

note

Analogy

• Product is the menu item (Latte).
• ProductPrice is the outlet specific price ($6.50 at Orchard, $7.20 at Marina Bay)

2. Commercial Documents (how customers buy)

Tables:

• billing_bill_to_profiles
• billing_invoices
• billing_invoice_lines
• billing_payments
• billing_invoice_postings

Generates and tracks customer-facing documents (invoices). Tracks payment status of each invoice (billing_payments). When payment is complete, it will "post" the entitlements linked to the invoice lines.

• billing_bill_to_profiles: who we bill for a company; the invoice copies these details at creation
• billing_invoices: are customer facing documents
• billing_payments: capture offline bank transfer with proof.
• billing_invoice_postings: is the internal step that grants entitlements only after payment is verified.

note

Restaurant Analogy

• Invoice: When you order something at the restaurant, you get a bill
• Payment: You make payment via bank transfer to the restaurants bank account. They receive it and gives a receipt.
• Posting: The kitchen gets the confirmed order (cause you already paid) and starts preparing your order.

3. Entitlements Engine (what customers can spend)

Tables:

• billing_entitlements
• billing_ledger_entries
• billing_entitlement_balances
• billing_entitlement_lots
• billing_entitlement_lot_allocations
• billing_credit_actions
• billing_credit_expiry_notices
• billing_outlet_budgets and billing_outlet_budget_transfers

We track the delta/change/diff of every instrument (:gig, :placement) for each action taken by the company.

• Ledger Entry is the single source of truth for all movements of credits
• Balance is the projection for fast reads.
  • How many credits do I have that can be used to purchase another 7-day job boost?
• The reserved credits of a deliverable are not stored. They are computed from the ledger entries naming that deliverable as source (Billing D8 — reserved credits are computed from the ledger).
• Lots exist for every stored-value instrument. Each grant creates one purchase batch (Billing D2 — all stored-value credits use entitlement lots).
• Credit actions are how an admin writes a ledger entry when no commercial document exists.
• Credit expiry notices are the send log of the credit expiry warning emails.
• Outlet budgets partition a company's balance into per-outlet spending buckets.

important

Notice that we are modelling the tables based on the financial process of tracking credit usage, not on the Ads or Gig domains. Every instrument runs through the same tables.

4. Reporting & Finance Exports (how we reconcile)

Outputs:

• SOA per company
• Finance export aggregates
• Xero-friendly journals/invoice exports

Statement of Accounts (SOA) are derived from ledger entries (grouped by reference) Finance exports are produced from the same ledger, but summarised to match finance workflows

• credit usage (daily/monthly)
• recognised revenue (daily/monthly)