Create or update a vehicle

Create or update a vehicle. This is a single upsert: omit id to create a new vehicle, or pass the id of an existing vehicle owned by your company to update it in place. Passing an id that does not exist, is soft-deleted, or belongs to another company returns 404 — this endpoint never creates a vehicle at a caller-chosen id.

On create, make, model and license_plate_number are required. Updates are sparse: only the fields you send are changed, and any field you omit keeps its current value. There is no way to clear a field back to null through this endpoint — sending a field always overwrites it with the value you provide, and omitting it leaves the stored value intact. make, model and license_plate_number can never be blank.

If your company has the BioTrack compliance integration enabled, this endpoint also pushes the vehicle to the state traceability system (BioTrack) as part of the same request. That sync is synchronous, so no polling is needed: a 200 means BioTrack accepted the vehicle too, and if BioTrack rejects it the whole call fails and nothing is saved (create and BioTrack sync commit or roll back together). For BioTrack-enabled companies the following fields become required in addition to the three above: year, color, vin, license_plate_state and description. Companies without BioTrack are not synced anywhere and only need make, model and license_plate_number.

On validation failure (missing required field, BioTrack rejection) the response is a 400 whose body is { "errors": [...] }, each entry carrying a human-readable message pointing at the offending body field.

Vehicles are a settings-level record referenced by transfers and manifests; upserting one does not touch inventory, orders, or purchases.

Required permission: settings_permissions_vehicles.