Revenue Recognition Agent

STEP 1: Identify the contract(s) with a customer
STEP 2: Identify the performance obligations in the contract
STEP 3: Determine the transaction price
STEP 4: Allocate the transaction price to the performance obligations
STEP 5: Recognize revenue when (or as) each obligation is satisfied

CONTRACT CRITERIA CHECKLIST (ASC 606-10-25-1)
─────────────────────────────────────────────
□ Parties have approved the contract (written, oral, or implied)
□ Each party's rights regarding goods/services are identifiable
□ Payment terms for the goods/services are identifiable
□ Contract has commercial substance
□ It is probable the entity will collect the consideration

1. CAPABLE OF BEING DISTINCT: Customer can benefit from 
   the good/service on its own or with readily available resources.

2. DISTINCT WITHIN THE CONTRACT: Promise is separately 
   identifiable from other promises in the contract.

Transaction Price Components
─────────────────────────────────────────────
1. FIXED CONSIDERATION
   → Contract price net of discounts

2. VARIABLE CONSIDERATION
   Types: discounts, rebates, refunds, credits, 
          price concessions, incentives, performance bonuses,
          royalties, contingent payments
   
   Estimation methods:
   a) Expected value (probability-weighted) — best for many outcomes
   b) Most likely amount — best for two outcomes (binary)
   
   CONSTRAINT: Include variable consideration only to the extent
   it is probable a significant revenue reversal will NOT occur.

3. SIGNIFICANT FINANCING COMPONENT
   If >12 months between payment and delivery AND financing is
   a significant benefit → adjust for time value of money.
   
   Practical expedient: If contract < 1 year, ignore financing.

4. NON-CASH CONSIDERATION
   Measure at fair value of non-cash consideration received.

5. CONSIDERATION PAYABLE TO CUSTOMER
   (Discounts, coupons, rebates)
   → Reduce transaction price unless payment is for distinct good/service

1. OBSERVABLE PRICE
   → Actual price when entity sells the good/service separately.
   → Best evidence. Use when available.

2. ADJUSTED MARKET ASSESSMENT APPROACH
   → Price the market would pay for the good/service.
   → Research competitor pricing, customer willingness to pay.

3. EXPECTED COST PLUS MARGIN APPROACH
   → Forecast costs to satisfy the obligation + appropriate margin.

4. RESIDUAL APPROACH (limited use)
   → SSP = Transaction price - sum of SSPs of other obligations.
   → Only permitted if SSP is highly variable or uncertain.

Contract: $12,000 annual SaaS deal
Includes: SaaS license + Implementation + Training

Element           SSP       Allocation %   Allocated Price
─────────────────────────────────────────────────────────
SaaS License      $10,000      71.4%          $8,571
Implementation    $2,500       17.9%          $2,143
Training          $1,500       10.7%          $1,286
─────────────────────────────────────────────
Total SSP         $14,000      100%           $12,000

Note: Contract price ($12k) is less than total SSP ($14k) —
the $2,000 discount is allocated proportionally across all obligations.

□ Customer simultaneously receives and consumes the benefits
  (→ SaaS subscriptions, most services)
□ Entity's performance creates or enhances an asset the 
  customer controls (→ customized software for customer)
□ Entity's performance creates no alternative use AND entity
  has right to payment for work completed to date (→ custom dev)

Indicators of control transfer:
□ Entity has right to payment
□ Customer has legal title
□ Entity has transferred physical possession
□ Customer has significant risks and rewards
□ Customer has accepted the asset

CONTRACT REVENUE SCHEDULE
─────────────────────────────────────────────────────────────
Contract:    Acme Corp — Annual SaaS License
Period:      March 1, 2026 – February 28, 2027
ARR:         $12,000 | MRR: $1,000
─────────────────────────────────────────────────────────────
Month        Days    Recognized     Cumulative    Deferred
─────────────────────────────────────────────────────────────
Mar 2026     31      $1,000         $1,000        $11,000
Apr 2026     30      $1,000         $2,000        $10,000
May 2026     31      $1,000         $3,000         $9,000
Jun 2026     30      $1,000         $4,000         $8,000
Jul 2026     31      $1,000         $5,000         $7,000
Aug 2026     31      $1,000         $6,000         $6,000
Sep 2026     30      $1,000         $7,000         $5,000
Oct 2026     31      $1,000         $8,000         $4,000
Nov 2026     30      $1,000         $9,000         $3,000
Dec 2026     31      $1,000        $10,000         $2,000
Jan 2027     31      $1,000        $11,000         $1,000
Feb 2027     28      $1,000        $12,000             $0
─────────────────────────────────────────────────────────────
TOTAL                $12,000

from dataclasses import dataclass
from datetime import date, timedelta
from typing import List, Optional
import math

@dataclass
class PerformanceObligation:
    name: str
    allocated_price: float
    recognition_pattern: str  # "point_in_time" | "over_time_straight_line" | "over_time_pct_complete"
    start_date: Optional[date] = None
    end_date: Optional[date] = None
    completion_date: Optional[date] = None  # for point in time
    pct_complete: float = 0.0  # for % complete method (0.0-1.0)

def calculate_recognized_revenue(
    obligation: PerformanceObligation,
    as_of_date: date
) -> float:
    """
    Calculate cumulative revenue recognized for an obligation as of a date.
    
    Examples:
        # SaaS subscription (over time, straight-line)
        sub = PerformanceObligation(
            name="SaaS License",
            allocated_price=8571,
            recognition_pattern="over_time_straight_line",
            start_date=date(2026, 3, 1),
            end_date=date(2027, 2, 28)
        )
        recognized = calculate_recognized_revenue(sub, date(2026, 6, 30))
        # → $2,857 (4 months of 12)
        
        # Training (point in time)
        training = PerformanceObligation(
            name="Training",
            allocated_price=1286,
            recognition_pattern="point_in_time",
            completion_date=date(2026, 3, 15)
        )
        recognized = calculate_recognized_revenue(training, date(2026, 4, 1))
        # → $1,286 (training already delivered)
    """
    if obligation.recognition_pattern == "point_in_time":
        if obligation.completion_date and as_of_date >= obligation.completion_date:
            return obligation.allocated_price
        return 0.0
    
    elif obligation.recognition_pattern == "over_time_straight_line":
        if not obligation.start_date or not obligation.end_date:
            raise ValueError("start_date and end_date required for straight-line")
        
        total_days = (obligation.end_date - obligation.start_date).days
        elapsed_days = min(
            (as_of_date - obligation.start_date).days,
            total_days
        )
        elapsed_days = max(0, elapsed_days)
        return obligation.allocated_price * (elapsed_days / total_days)
    
    elif obligation.recognition_pattern == "over_time_pct_complete":
        return obligation.allocated_price * min(obligation.pct_complete, 1.0)
    
    return 0.0


def deferred_revenue_balance(
    obligations: List[PerformanceObligation],
    invoiced_amount: float,
    as_of_date: date
) -> dict:
    """
    Calculate deferred revenue and recognized revenue balances.
    
    Returns:
        total_recognized, total_deferred, per_obligation breakdown
    """
    results = []
    total_recognized = 0.0
    
    for ob in obligations:
        recognized = calculate_recognized_revenue(ob, as_of_date)
        deferred = ob.allocated_price - recognized
        total_recognized += recognized
        results.append({
            "obligation": ob.name,
            "allocated_price": ob.allocated_price,
            "recognized": round(recognized, 2),
            "deferred": round(deferred, 2),
        })
    
    return {
        "as_of_date": as_of_date.isoformat(),
        "invoiced": invoiced_amount,
        "total_recognized": round(total_recognized, 2),
        "total_deferred": round(invoiced_amount - total_recognized, 2),
        "obligations": results,
    }

DR  Cash / Accounts Receivable          $12,000
    CR  Deferred Revenue                    $12,000
(Record contract liability at contract start)

DR  Deferred Revenue                    $1,000
    CR  Revenue — SaaS Subscriptions        $1,000
(Recognize ratably each month over 12-month term)

DR  Accounts Receivable                 $12,000
    CR  Deferred Revenue — SaaS             $8,571
    CR  Deferred Revenue — Implementation   $2,143
    CR  Deferred Revenue — Training         $1,286
(Allocate to performance obligation buckets at contract inception)

DR  Deferred Revenue — Training         $1,286
    CR  Revenue — Professional Services     $1,286
(Recognize at point in time — training delivered)

DR  Deferred Revenue — Implementation   $2,143
    CR  Revenue — Professional Services     $2,143
(Recognize at point in time — implementation accepted)

DR  Deferred Revenue — SaaS             $714.25
    CR  Revenue — SaaS Subscriptions        $714.25
($8,571 ÷ 12 months = $714.25/month)

DR  Revenue                             $500
    CR  Refund Liability                    $500
(Constrain estimated refunds — reverse when constraint resolved)