Battery Capacity

curl "https://api.smartcar.com/v2.0/vehicles/{id}/battery/nominal_capacity" \
-H "Authorization: Bearer {token}" \
-X "GET"

{
    "availableCapacities": [
        {
            "capacity" :  70.9,
            "description" : "BEV" 
        },
        {
            "capacity" :  80.9,
            "description" : "BEV"
        },
        {
            "capacity" :  90.9,
            "description" : "BEV" 
        }
    ],
    "capacity": { 
	    "nominal" :  80.9,
	    "source": "USER_SELECTED" 
    },
    "url" : "https://connect.smartcar.com/battery-capacity?vehicle_id=36ab27d0-fd9d-4455-823a-ce30af709ffc&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07&token=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad&response_type=vehicle_id&redirect_uri="
} 

curl "https://api.smartcar.com/v2.0/vehicles/{id}/battery/nominal_capacity" \
-H "Authorization: Bearer {token}" \
-X "GET"

{
    "availableCapacities": [
        {
            "capacity" :  70.9,
            "description" : "BEV" 
        },
        {
            "capacity" :  80.9,
            "description" : "BEV"
        },
        {
            "capacity" :  90.9,
            "description" : "BEV" 
        }
    ],
    "capacity": { 
	    "nominal" :  80.9,
	    "source": "USER_SELECTED" 
    },
    "url" : "https://connect.smartcar.com/battery-capacity?vehicle_id=36ab27d0-fd9d-4455-823a-ce30af709ffc&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07&token=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad&response_type=vehicle_id&redirect_uri="
} 

The Vehicles API v2.0 will be deprecated on December 1, 2026. The latest version, v3, was introduced on August 26, 2025. We recommend migrating as soon as possible to ensure continued support and access to new features.

Permission

read_battery

Request

Path

string

required

The vehicle ID of the vehicle you are making a request to.

curl "https://api.smartcar.com/v2.0/vehicles/{id}/battery/nominal_capacity" \
-H "Authorization: Bearer {token}" \
-X "GET"

Response

[capacities Object]

An array of capacities Objects.

Show capacities

number | null

default:"kWh"

The rated nominal capacity for the vehicle’s battery.

string

The engine type of the vehicle for this capacity, either BEV or PHEV. Only these two are offered — a battery capacity is not a meaningful question for any other powertrain.Capacities that share a battery pack are returned once, so this value repeats across entries and capacity is what distinguishes them. A vehicle offered in several trims on the same pack therefore returns a single entry.

Object | null

Show capacity

number | null

default:"kWh"

The rated nominal capacity for the vehicle’s battery.

string | null

Indicates if this capacity was determined by a user or Smartcar. Options are USER_SELECTED or SMARTCAR.

string | null

A URL that will launch the flow for a vehicle owner to specify the correct battery capacity for a vehicle. Please ensure you append a redirect URI for us to send a response to once the user exits the flow.Please see this article on how to handle the URL callback.

{
    "availableCapacities": [
        {
            "capacity" :  70.9,
            "description" : "BEV" 
        },
        {
            "capacity" :  80.9,
            "description" : "BEV"
        },
        {
            "capacity" :  90.9,
            "description" : "BEV" 
        }
    ],
    "capacity": { 
	    "nominal" :  80.9,
	    "source": "USER_SELECTED" 
    },
    "url" : "https://connect.smartcar.com/battery-capacity?vehicle_id=36ab27d0-fd9d-4455-823a-ce30af709ffc&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07&token=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad&response_type=vehicle_id&redirect_uri="
} 

Case 1: Smartcar has determined the battery capacity

Single capacity

{
    "availableCapacities": [
        {
            "capacity" :  70.9,
            "description" : "BEV"  
        }
    ],
    "capacity": { 
        "nominal" :  70.9,
        "source": "SMARTCAR" 
    },
    "url" : null
} 

Case 2: Unable to determine the battery capacity

Multiple capacities

{
    "availableCapacities": [
        {
            "capacity" :  70.9,
            "description" : "BEV" 
        },
        {
            "capacity" :  80.9,
            "description" : "BEV" 
        },
        {
            "capacity" :  90.9,
            "description" : "BEV" 
        }
    ],
    "capacity": null,
    "url" : "https://connect.smartcar.com/battery-capacity?vehicle_id=36ab27d0-fd9d-4455-823a-ce30af709ffc&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07&token=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad&response_type=vehicle_id&redirect_uri="
} 

Case 3: User selected battery capacity

Smartcar will sometimes return an availableCapacities object along side a Connect URL you can use to prompt users to select the battery capacity of their vehicle. This can occur when an accurate match could not be found, or vehicle owners purchased extension packs, or software upgrades specific to their vehicle. When you redirect a vehicle owner to this Smartcar Connect url, they can select the battery capacity of their vehicle for cases where the battery capacity cannot be accurately determined.

Battery capacity user selection in Connect

When a user selects an option, Smartcar will return this value with USER_SELECTED as the source.

Multiple capacities

{
  "availableCapacities": [
    {
      "capacity": 70.9,
      "description": "BEV" 
    },
    {
      "capacity": 80.9,
      "description": "BEV" 
    },
    {
      "capacity": 90.9,
      "description": "BEV" 
    }
  ],
  "capacity": { 
    "nominal": 80.9,
    "source": "USER_SELECTED" 
  },
  "url": "https://connect.smartcar.com/battery-capacity?vehicle_id=36ab27d0-fd9d-4455-823a-ce30af709ffc&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07&token=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad&response_type=vehicle_id&redirect_uri="
}

Introduction

Authorization

Connections

Webhooks

Vehicle Data

Vehicle Commands

Vehicle Settings

Interactions

Compatibility

API 2.0 Reference (Legacy)

Vehicle Commands (Legacy)

Management API (Legacy)

Compatibility API (Legacy)

Permission

Request

Response

Case 1: Smartcar has determined the battery capacity

Case 2: Unable to determine the battery capacity

Case 3: User selected battery capacity

​Permission

​Request

​Response

​Case 1: Smartcar has determined the battery capacity

​Case 2: Unable to determine the battery capacity

​Case 3: User selected battery capacity

Permission

Request

Response

Case 1: Smartcar has determined the battery capacity

Case 2: Unable to determine the battery capacity

Case 3: User selected battery capacity