Skip to main content
Commands let your application take action on a vehicle. Unlike signals, which read vehicle state, commands write to it — they alter the data or state of the vehicle.

Available Commands

Charge schedules are supported on a subset of makes. Requests for a vehicle whose make does not support them return a VEHICLE_NOT_CAPABLE compatibility error:
After creating a schedule, read it back from the ChargeTimers signal. Timers with "type": "LOCATION" include a scheduleType and scheduleId — use the scheduleId to issue DELETE requests. The signal reflects all schedules on the vehicle, including any set outside of the API.

Data State Changes

Commands do not return updated vehicle state. After issuing a command, confirm or monitor its effect by reading the corresponding signal — via the Vehicle Data API or webhooks. Signal updates may be delayed as the change propagates to the vehicle.

Key Concepts

Always handle a 202

Any command or charge schedule request can return 202 Accepted, no matter how long you wait. Your integration must expect a 202 on every request and handle it as described below. Smartcar works in the background to get each request through to the vehicle. How long that takes varies widely, even for the same command on the same vehicle. A request that finished in seconds yesterday can take minutes today, so a longer wait reduces how often you get a 202 but never rules it out. A 202 is neither an error nor the final result. It’s a complete response: the body holds the execution with status.value set to PENDING, and the request keeps running after you receive it. To get the outcome, poll the execution URL until the status changes.
Don’t treat a 202 as a failure, and don’t rely on a long wait time to avoid one. Build polling into every code path that sends a command.

Setting the wait time

Each request waits up to 60 seconds by default before responding. Send Prefer: wait=<seconds> to change this, from 0 up to a maximum of 150 seconds:
  • If the request finishes in time, you get the final result: 200 with the execution, or an error status with an error response.
  • If it’s still running when the wait ends, you get a 202 instead of a timeout.
If you send a valid wait, the 200 or 202 response includes a Preference-Applied header with the wait that was used, for example Preference-Applied: wait=150.
If your client has a read timeout, set it above your wait time (more than 150 seconds if you send wait=150). Otherwise the client can give up before the response arrives. If you’d rather never block, send Prefer: wait=0 and poll from the start.

Getting the result after a 202

1

Read the 202 response

The Location header holds the URL of the execution. It’s the same value as data.links.self in the body. The Retry-After header says how many seconds to wait before checking.
2

Poll the execution

After Retry-After seconds, send a GET to the Location URL with the same Authorization header. Commands use Get command execution; charge schedules use Get charge schedule execution.
3

Repeat until it's no longer PENDING

Keep polling every Retry-After seconds until status.value is SUCCESS, FAILURE, or EXPIRED.
Every request reaches a final status, so polling always ends. See the execution endpoints for details on timing. EXPIRED means the request reached Smartcar’s time limit before a result was recorded, so the outcome is unknown. You can check the outcome in signal data or retry the command.
To confirm that an execution belongs to your request, compare its meta.requestId to the X-Amzn-Requestid header in the POST’s response. If they don’t match, the execution describes a newer operation.
Don’t send the same command again while the first one is still PENDING. Poll the Location URL instead. Related commands, such as lock and unlock or start and stop charging, also can’t run at the same time. While one of these commands is running, a duplicate or conflicting request is rejected with a 409 OPERATION_IN_PROGRESS error. Each endpoint lists the operations it conflicts with. The error’s meta.blockingOperation.links.self points to the running execution, so you can poll it and retry once it completes.

sc-user-id Header

All command endpoints require the sc-user-id header. Your bearer token is application-level and does not carry per-user context, so this header must be provided on every request to identify which user’s vehicle to act on.