Vehicle Settings Overview

Override values Smartcar derives for a vehicle, such as the nominal battery capacity, with the V3 vehicle settings endpoints.

Vehicle settings let your application override a value that Smartcar would otherwise derive for a vehicle. Each setting feeds one or more signals. After you set a value, read it back from those signals.

A setting is stored once per vehicle, not per application. Every application connected to the vehicle sees the same value.

Available Settings

Setting	Endpoint	Affected signal
Nominal battery capacity	POST /vehicles/{vehicleId}/settings/tractionbattery-nominalcapacity	TractionBattery.NominalCapacity

Setting codes match the code of the signal they affect.

Nominal Battery Capacity

For some vehicles, Smartcar can’t determine the nominal battery capacity on its own. In that case, the TractionBattery.NominalCapacity signal lists the options in availableCapacities, and capacity stays empty until someone chooses.

You can resolve it in one of two ways:

• Set the capacity yourself if your application already knows it. Use Set nominal battery capacity.
• Ask the vehicle owner to choose it. Create a select-battery-capacity interaction and send the owner the URL it returns.

1. Read the available capacities

   Call GET /vehicles/{vehicleId}/signals/tractionbattery-nominalcapacity. Use one of the values in availableCapacities.

2. Set the capacity

   curl https://vehicle.api.smartcar.com/v3/vehicles/{vehicleId}/settings/tractionbattery-nominalcapacity \
     -X POST \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "sc-user-id: {userId}" \
     -H "Content-Type: application/json" \
     -d '{ "data": { "attributes": { "capacity": 75 } } }'
   
3. Read the new value

   The response confirms the value and links to the affected signal. The signal then returns the new capacity with source set to APPLICATION.

Source of the value

The source field on the signal tells you who decided the current capacity:

source	Meaning
SMARTCAR	Smartcar determined it.
USER_SELECTED	The vehicle owner selected it in Smartcar Connect.
APPLICATION	An application set it with the settings endpoint.

The most recent value wins, whoever set it. If the vehicle owner selects a capacity in Connect after an application set one, the owner’s selection replaces it, and the reverse is also true.

Simulated vehicles

Simulated vehicles accept any capacity from 10 to 200 kWh.

Key Concepts

sc-user-id Header

Like commands, settings endpoints require the sc-user-id header. It identifies the user whose connection to the vehicle your application acts through.

Errors

Status	code	When
400	INVALID_INPUT_FORMAT	The request body is malformed, or capacity isn’t a positive number.
400	MISSING_PARAMETER	The sc-user-id header is missing.
400	INVALID_SETTING_VALUE	capacity isn’t one of the vehicle’s available capacities. The detail lists the valid values.
404	VEHICLE_NOT_FOUND	The vehicle isn’t connected to your application.
404	SETTING_NOT_SUPPORTED	The vehicle has no available capacities, for example because it has no high voltage battery.