prepare_dealer_handoff
Use this when the shopper has picked a car and a deal structure and wants to take it to the dealer. Builds a structured dealer handoff package for ONE configured deal: vehicle and VIN, the full itemized out-the-door estimate (with excluded items such as optional add-ons), the chosen financing scenario with demo financing eligibility, trade and negative-equity details (loan-to-value), all warnings, the assistant name and session reference, a timestamp (UTC and America/Chicago) and an estimate-not-offer disclaimer. Returns the package as JSON plus a ready-to-send email body (email.subject, email.text, email.html) with no recipient filled in. THIS TOOL SENDS NOTHING and contacts no one: delivery.status is not_sent, and delivery happens later, with the shopper's consent, through the dealer's chosen channel (email, desking or F&I). No dealer email is invented; dealer.handoff_contact is null until the dealer provides one. On synthetic data the package is labeled DEMO. Before calling, ask the shopper for a phone number or email for the dealer (with their OK); the call fails without a phone, email, or a name plus preferred_contact. The deal (date, shopper name and contact, car, payment, status) is saved to the store's dealer dashboard, where only that store, its region and group can see the contact info and address. Optional extras the dealer will use: trade_details (VIN, miles, plate, color, who the loan is with and how much), buyer_address (with county, for tax and registration), financing_details (deposit, cash down and rebates as separate lines, and any lender pre-approval the shopper already has) and add_on_interest (yes, no or unsure for service contract, GAP, maintenance, other; never priced). The email has a deal sheet in buyer's order line order including the store's dealer fees. NEVER ask the shopper for a Social Security number (or any part of one), date of birth or income; the tool rejects them. Leases, add-on pricing and payment dates are left to the dealer.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| vin | No | 17-character VIN, if listing_id is not known. Rejected if several dealers list it. | |
| payoff | No | Loan payoff owed on the trade-in, USD. | |
| scenario | No | The financing scenario the shopper chose, same shape as one compare_payment_scenarios scenario (down_payment, term_months, credit_tier or apr, trade fields, or cash=true). Default: $0 down, 60 months, good credit. | |
| assistant | No | Optional assistant reference: name, session_ref, contact. | |
| buyer_zip | No | Buyer's five-digit ZIP; alone it resolves state, county and city. | |
| buyer_city | No | Buyer's city. | |
| listing_id | No | dealer_key:VIN from search_inventory. Either this or vin is required. | |
| buyer_state | No | Buyer's two-letter state. | |
| trade_value | No | Trade-in allowance in USD (used when the scenario does not set it). | |
| buyer_county | No | Buyer's county without 'County'. | |
| trade_equity | No | Net trade equity if allowance and payoff are unknown (no tax credit). | |
| buyer_address | No | Optional shopper address (street, city, state, zip, county), with their OK. Sets tax and registration; visible only to the deal's store, region and group. | |
| trade_details | No | Optional trade-in details from the shopper: year, make, model, trim, vin, odometer, plate, plate_state, color, payoff_lender, payoff_amount. | |
| trade_vehicle | No | Short description of the trade, e.g. '2021 Ford F-150 XLT, 48k mi'. | |
| add_on_interest | No | Optional: is the shopper interested in service_contract, gap, maintenance, other (yes, no or unsure)? No prices; the dealer covers these. | |
| shopper_contact | No | REQUIRED. Ask the shopper how the dealer should reach them, and share only with their OK: name, phone and/or email, preferred_contact (call, text or email), notes. Needs a phone or email, or a name plus preferred_contact. | |
| financing_details | No | Optional separate deposit, cash_down and rebates (they add up to the down payment), plus pre_approval (has_pre_approval, lender_name, approved_amount, rate_percent; the rate is used for the payment unless scenario.apr is set). NEVER ask for a Social Security number or any part of one, date of birth or income. | |
| eligible_incentive_labels | No | Conditional incentive label_raw values the shopper qualifies for. |