System Overview
Mixbound Microservice: HubSpot ACV Correction
Purpose
A Node.js microservice that automatically calculates and corrects Annual Contract Value (ACV) for HubSpot deals based on their associated line items with recurring billing information. Provides four financial models across calendar and fiscal year boundaries for multi-dimensional revenue modeling.
Four-Model Financial Architecture
Booked ACV (Calendar-Year)
"Booked annual contract value allocated to calendar years"
Bucketing: Calendar year of line item start date (YYYY), spread across term years
Lens: Sales / Bookings / GTM
Writes: acv_2025 … acv_2030, corrected_acv
Booked ACV (Fiscal-Year)
"Same booked ACV, allocated into fiscal years"
Bucketing: Fiscal year boundaries (configurable start month)
Default: FISCAL_YEAR_START_MONTH=2 → FY runs Feb–Jan
Writes: acv_fy_2025 … acv_fy_2030, corrected_acv_fy, fiscal_year
Prorata ACV (Calendar-Year)
"Recognized value allocated by daily prorating into calendar years"
Bucketing: Daily rate from annualized value, allocated across calendar year segments
Lens: Finance / Forecasting / Cash Flow
Writes: prorata_acv_2025 … prorata_acv_2030, prorata_corrected_acv
Prorata ACV (Fiscal-Year)
"Same daily prorated allocation, bucketed into fiscal years"
Bucketing: Same daily prorating, into fiscal year segments
Default: Uses same FISCAL_YEAR_START_MONTH setting
Writes: prorata_acv_fy_2025 … prorata_acv_fy_2030, prorata_corrected_acv_fy
Fiscal Year Configuration
Controlled by FISCAL_YEAR_START_MONTH (1–12). Default: 2 (February).
With default (month = 2):
- FY2025 = Feb 2025 → Jan 2026
- FY2026 = Feb 2026 → Jan 2027
- FY2027 = Feb 2027 → Jan 2028
The fiscal_year property stores a label like "1 feb - 1 jan".
Key Capabilities
Four-Model ACV Calculation
Computes Booked and Prorata ACV across both calendar and fiscal year boundaries
Year Bucket Analysis
Distributes ACV across year buckets (2025-2030) for all four financial models
Schema Guard Protection
Safely skips missing HubSpot properties — deploy only the models you need
Bulk Backfill
Scans and recalculates all four models for all deals with line items
System Inputs & Outputs
→ Inputs
- • Deal ID (from webhook/trigger)
- • Line item recurring fields
- • Billing periods & start dates
- • Amount, price, quantity
← Outputs
corrected_acv acv_2025 … acv_2030corrected_acv_fy acv_fy_2025 … acv_fy_2030 fiscal_yearprorata_corrected_acv prorata_acv_2025 … prorata_acv_2030prorata_corrected_acv_fy prorata_acv_fy_2025 … prorata_acv_fy_2030deal_close_date on line itemsField Naming Conventions
| Model | Year Buckets | Summary |
|---|---|---|
| Calendar Booked | acv_<year> |
corrected_acv |
| Fiscal Booked | acv_fy_<year> |
corrected_acv_fy |
| Calendar Prorata | prorata_acv_<year> |
prorata_corrected_acv |
| Fiscal Prorata | prorata_acv_fy_<year> |
prorata_corrected_acv_fy |
Additional fiscal property: fiscal_year — single-line text label (e.g., "1 feb - 1 jan")