Vehicle Settings Overview

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.

Read the available capacities

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

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 } } }'

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.

Introduction

Authorization

Connections

Webhooks

Vehicle Data

Vehicle Commands