cost-seg-smart

{'type': 'object', 'required': ['property_type', 'purchase_price'], 'properties': {'zip': {'type': 'string', 'description': 'Optional. Property ZIP code (5-digit or ZIP+4).'}, 'city': {'type': 'string', 'description': 'Optional. Property city. Used for the report cover page and metro-specific cost adjustments.'}, 'name': {'type': 'string', 'description': "Optional. Buyer's full name for the report cover page."}, 'sqft': {'type': 'integer', 'description': 'Optional. Building square footage. Improves cost-per-square-foot accuracy in the final report.'}, 'state': {'type': 'string', 'description': "Optional. Two-letter US state code (e.g. 'CA', 'TX'). Used for state-tax adjustments where applicable."}, 'address': {'type': 'string', 'description': 'Optional. Property street address. Improves report accuracy via county parcel data lookup post-purchase.'}, 'bedrooms': {'type': 'integer', 'description': 'Optional. Number of bedrooms (residential only).'}, 'bathrooms': {'type': 'number', 'description': 'Optional. Number of bathrooms (residential only). Half-baths count as 0.5.'}, 'year_built': {'type': 'integer', 'description': 'Optional. Year the property was originally constructed. Drives era-specific component cost adjustments.'}, 'buyer_email': {'type': 'string', 'format': 'email', 'description': 'Optional. Pre-fills the email field on the Stripe Checkout page. If omitted, Stripe collects it from the buyer at checkout.'}, 'property_type': {'enum': ['sfr', 'str', 'condo', 'condo_str', 'adu', 'duplex', 'triplex', 'fourplex', 'multifamily_small', 'multifamily', 'multifamily5', 'office', 'retail', 'industrial', 'mixed_use', 'medical_office', 'restaurant', 'duplex_str', 'triplex_str', 'fourplex_str'], 'type': 'string', 'description': 'Property type identifier. Must match one of the enum values supported by get_cost_seg_quote.'}, 'purchase_price': {'type': 'integer', 'minimum': 25000, 'description': 'Property purchase price in US dollars. Minimum $25,000. Pricing tier is computed from this value.'}, 'acquisition_date': {'type': 'string', 'format': 'date', 'description': "Strongly recommended. ISO 'YYYY-MM-DD'. The date the buyer PURCHASED the property (closing/recorded transfer date), which may differ from placed_in_service_date. Both dates together set the bonus-depreciation rate; omitting both makes the study assume TODAY, which yields the maximum rate and holds the order for human review. Ask the buyer."}, 'agent_attribution': {'type': 'string', 'description': "Optional. Overrides the X-Agent-Name request header. Use the user-visible name of your agent (e.g. 'Claude', 'ChatGPT', 'Cursor') so the buyer's checkout disclaimer correctly identifies who prepared the order. Establishes a chargeback-defense paper trail."}, 'placed_in_service_date': {'type': 'string', 'format': 'date', 'description': "Strongly recommended. ISO 'YYYY-MM-DD'. The date the property was placed in service (available for rent or use). Together with acquisition_date this determines the bonus-depreciation RATE, which is the single largest driver of the Year-1 deduction. If you omit both dates the study assumes TODAY, which yields the maximum bonus rate — the order is then held for human review rather than delivered. Ask the buyer for this date."}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'tier': {'enum': ['institutional_custom'], 'type': 'string', 'description': 'Present only when the property is in the institutional custom-quote tier (purchase_price >= $25M).'}, 'message': {'type': 'string', 'description': 'Present only for the institutional tier. Human-readable explanation to surface to the buyer.'}, 'currency': {'enum': ['USD'], 'type': 'string', 'description': "Always 'USD' when present."}, 'next_step': {'type': 'string', 'description': "Human-readable instruction for the agent's next action."}, 'agent_name': {'type': 'string', 'description': "Agent name as it appears in the buyer's checkout disclaimer."}, 'disclaimer': {'type': 'string', 'description': 'Full liability disclaimer embedded in the Stripe Checkout description. Show this to the buyer alongside the link.'}, 'study_cost': {'type': 'integer', 'description': 'Study cost in USD the buyer will be charged. Present only for fixed-price tiers.'}, 'contact_email': {'type': 'string', 'format': 'email', 'description': 'Present only for the institutional tier. Route the buyer here for a custom-scoped engagement quote.'}, 'property_type': {'enum': ['sfr', 'str', 'condo', 'condo_str', 'adu', 'duplex', 'triplex', 'fourplex', 'multifamily_small', 'multifamily', 'multifamily5', 'office', 'retail', 'industrial', 'mixed_use', 'medical_office', 'restaurant', 'duplex_str', 'triplex_str', 'fourplex_str'], 'type': 'string', 'description': 'Echo of the requested property_type.'}, 'purchase_price': {'type': 'integer', 'description': 'Echo of the requested purchase_price.'}, 'agent_order_ref': {'type': 'string', 'description': 'Internal correlation ID for this agent-initiated order.'}, 'payment_link_url': {'type': ['string', 'null'], 'description': 'Stripe Checkout URL for the buyer to click. Null for the institutional custom-quote tier — when null, see contact_email.'}, 'stripe_session_id': {'type': 'string', 'description': 'Stripe Checkout Session ID (cs_live_... or cs_test_...). Present only when payment_link_url is non-null.'}, 'property_type_label': {'type': 'string', 'description': 'Human-readable property type label.'}}, 'description': 'Returns one of two shapes depending on price tier: a Stripe Checkout URL (fixed-price tiers) or an institutional-custom routing object (price >= $25M). payment_link_url is the discriminator — string when actionable, null when custom-routed.'}

{'type': 'object', 'required': ['property_type', 'purchase_price'], 'properties': {'tax_bracket': {'type': 'number', 'description': "Optional. Buyer's federal marginal tax bracket. Accepts decimal form (0.0-0.6, e.g. 0.32 for 32%) OR whole-number percent (0-60). When provided, response includes tax_savings_year_one and roi_multiple. When omitted, response only includes the deduction estimate."}, 'property_type': {'enum': ['sfr', 'str', 'condo', 'condo_str', 'adu', 'duplex', 'triplex', 'fourplex', 'multifamily_small', 'multifamily', 'multifamily5', 'office', 'retail', 'industrial', 'mixed_use', 'medical_office', 'restaurant', 'duplex_str', 'triplex_str', 'fourplex_str'], 'type': 'string', 'description': 'Property type identifier. Determines the pricing tier and the default Year-1 reclassification percentage. Residential types (sfr, str, condo, condo_str, adu) reclassify ~22-30%; small multifamily (duplex/triplex/fourplex) ~27%; commercial varies by subtype (~18-30%).'}, 'purchase_price': {'type': 'integer', 'minimum': 25000, 'description': 'Property purchase price in US dollars. Minimum $25,000. The pricing tier is computed from this value. Properties >= $25M fall in the institutional custom-quote tier.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['property_type', 'property_type_label', 'purchase_price', 'study_cost_tier', 'deduction_estimate_year_one', 'currency', 'next_step', 'disclaimer'], 'properties': {'currency': {'enum': ['USD'], 'type': 'string', 'description': "Always 'USD' — Cost Seg Smart is US-only."}, 'next_step': {'type': 'string', 'description': "Human-readable instruction for the agent's next call."}, 'disclaimer': {'type': 'string', 'description': 'Standard estimate disclaimer to show the buyer.'}, 'study_cost': {'type': ['integer', 'null'], 'description': 'Study cost in USD. Null for the institutional custom-quote tier (price >= $25M) — see study_cost_tier.'}, 'roi_multiple': {'type': ['integer', 'null'], 'description': 'Year-1 return on the study fee = tax_savings_year_one / study_cost, rounded to integer. Null when tax_bracket was not provided or study_cost is null.'}, 'property_type': {'enum': ['sfr', 'str', 'condo', 'condo_str', 'adu', 'duplex', 'triplex', 'fourplex', 'multifamily_small', 'multifamily', 'multifamily5', 'office', 'retail', 'industrial', 'mixed_use', 'medical_office', 'restaurant', 'duplex_str', 'triplex_str', 'fourplex_str'], 'type': 'string', 'description': 'Echo of the requested property_type.'}, 'purchase_price': {'type': 'integer', 'description': 'Echo of the requested purchase_price (USD).'}, 'study_cost_tier': {'enum': ['fixed_price', 'institutional_custom'], 'type': 'string', 'description': "'fixed_price' = study_cost is a real USD amount. 'institutional_custom' = property is in the $25M+ tier; route the buyer to support@costsegsmart.com."}, 'property_type_label': {'type': 'string', 'description': "Human-readable label (e.g. 'Short-Term Rental')."}, 'tax_savings_year_one': {'type': ['integer', 'null'], 'description': 'Estimated Year-1 federal tax savings in USD = deduction_estimate_year_one × tax_bracket. Null when tax_bracket was not provided.'}, 'deduction_estimate_year_one': {'type': 'integer', 'description': 'Estimated Year-1 accelerated depreciation in USD, computed as purchase_price × (1 - 0.18 land) × reclass_pct[property_type]. Assumes 100% bonus depreciation per OBBBA §168(k) (2025+).'}}}