Skip to main content

Billing Layers

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.

Billing Schema Design

1. Catalog & Pricing (what we sell)​

Tables:

  • billing_products
  • billing_products_entitlements
  • billing_products_prices
  • billing_offers
  • billing_legal_entities (Jod companies)

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

  • "gig credits"
  • "placement credits"

An offer defines how we sell the product in 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).
  • Offer is the outlet specific price ($6.50 at Orchard, $7.20 at Marina Bay)

2. Commercial Documents (how customers buy)​

Tables:

  • billing_invoices
  • billing_invoice_items
  • billing_payments
  • billing_invoice_postings

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

  • 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_entitlement_types
  • billing_ledger_entries
  • billing_entitlement_balances
  • billing_entitlement_hold
  • gig-only
    • billing_entitlement_lots
    • billing_entitlement_lot_allocations

We track the delta/change/diff of every entitlement type (gig_credits, placement_credits) to each action taken by the company.

  • Ledger Entry is the single source of truth for all movements of credits
  • Balances & Holds are projections for fast reads.
    • How many credits do I have on hold?
    • How many credits do I have that can be used to purchase another 7-day job boost?
  • Lots exists only for instruments that require FIFO & per-purchase terms (i.e. Gig credits)
important

Notice that we are modelling the tables based on the financial process of tracking credit usage? It just so happens to only be used by Gig now.

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)