> ## Documentation Index
> Fetch the complete documentation index at: https://smartcar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://smartcar.com/docs/api-reference/signals/schema.md). 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`](https://smartcar.com/docs/api-reference/set-nominal-battery-capacity) | [`TractionBattery.NominalCapacity`](https://smartcar.com/docs/api-reference/signals/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`](https://smartcar.com/docs/api-reference/signals/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](https://smartcar.com/docs/api-reference/set-nominal-battery-capacity.md).
* **Ask the vehicle owner** to choose it. Create a [select-battery-capacity interaction](https://smartcar.com/docs/api-reference/interactions/overview.md) 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**

```bash theme={null}
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](https://smartcar.com/docs/getting-started/dashboard/simulator.md) accept any capacity from 10 to 200 kWh.

## Key Concepts

### sc-user-id Header

Like [commands](https://smartcar.com/docs/api-reference/commands/overview.md), 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. |