VIN Decoder Integration (Mechanics)

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €24/mo; credential: we license NHTSA/Edmunds VIN database

Generated from docs/plan/paid/vin-decoder-integration/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Automotive retailers allow customers to enter a VIN, which auto-populates engine specs, trim, year, and compatible parts. The paid pack licenses the VIN database (NHTSA, Edmunds) and provides monthly updates; core owns the lookup interface and part matching logic.

The problem

Customers buying automotive parts don’t know their exact engine, trim, or year. Typing a VIN auto-fills the vehicle details and shows only compatible parts, reducing wrong-part returns. Mechanics and parts retailers need this to match inventory.

What it does

• VIN decoder endpoint that returns: year, make, model, trim, engine displacement, fuel type, transmission
• Part compatibility matrix: when a part is tagged with engine type/year range, it is only shown to customers whose VIN matches
• Cart pre-population: customer enters VIN once, cart auto-selects only compatible parts from their search
• Admin UI to upload/update VIN database and part compatibility rules
• Webhook on VIN decode error (invalid VIN, year mismatch) to notify customer
• Test mode with 500 sample VINs for development
• Caching: VIN decodes are cached for 30 days (vehicle details don’t change)
• Error handling: malformed VIN, VIN not in database, API timeout

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Recall data: VINs may indicate vehicles with recalls, but liability and accuracy checks are the merchant’s responsibility (we only decode specs).
• Odometer lookup: consumer privacy and accuracy cannot be guaranteed; merchants must not build business logic on this.
• Title and registration status: this is sensitive PII; we do not query or store it (legal risk).
• Cross-platform VIN lookup: we return specs; merchants integrate with their own part inventory system (not AstroBaaS responsibility).

Data model

New document type: vin_decode { vin (hashed), year, make, model, trim, engine, fuel, transmission, cached_at }. New collection: part_compatibility { partId, compatible_years (array), compatible_makes (array), compatible_engines (array) }.

API

• POST /api/vin/decode { vin } -> { year, make, model, trim, engine, fuel, transmission, cached }
• GET /api/vin/compatibility?partId=ABC123 -> { compatible_years, compatible_makes, compatible_engines }
• POST /api/vin/admin/upload-database { csvFile } (admin only)
• GET /api/vin/cache-stats (admin only)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin sees: VIN database version and last update date, sample VIN test tool, compatibility matrix editor (upload CSV or edit per-part), cache hit rate, decode error log. Operator can upload new database monthly.

The seam — why this is paid

Core owns the VIN decode endpoint and part compatibility matching. Paid pack owns: VIN database license (NHTSA/Edmunds), monthly database updates, production database refresh schedule.

Credential: VIN database license (NHTSA), monthly updates, integration support

Dependencies

• product-variants subsystem (existing; parts are tagged with engine specs)
• cart subsystem (existing; pre-population on VIN lookup)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• VIN ‘1HGBH41JXMN109186’ (2000 Honda Civic) returns year=2000, make=‘Honda’, model=‘Civic’
• A part tagged as compatible with Honda Civic 1999-2002 is shown in filtered search for that VIN
• A part tagged as compatible with Toyota 4Runner is NOT shown for the Honda Civic VIN
• Second decode of the same VIN returns cached result within 30 days
• An invalid VIN ‘123ABC’ returns error with customer message
• Admin can upload a CSV with 100 VINs and see them searchable immediately after
• In test mode, VIN ‘TESTVIN0000000001’ returns predictable test data
• Decode error is logged with VIN (hashed), error reason, timestamp

Risks

If VIN is stored in plaintext in logs, privacy is compromised. If compatibility matrix is not rebuilt after database update, old parts show for new VINs. If cache TTL is too long, customers see stale vehicle data after database update. If VIN hash is reversible, it leaks vehicle details. If API timeout is not handled, checkout stalls.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.