---
title: "YMM Options"
description: "Populate Year, Make, Model, and Variant dropdown menus — one API call returns one layer."
canonical_url: "https://docs-staging.carsxe.com/docs/products/ymm-options"
markdown_url: "https://docs-staging.carsxe.com/docs/products/ymm-options.md"
last_updated: "1980-01-01"
x_farming_labs_generated_preamble: true
agent:
  task: "Populate cascading Year/Make/Model/Variant dropdown menus with CarsXE."
  outcome: "A YMM Options request returns the documented successful vehicle-data response for the supplied input."
  prerequisites:
    - "A valid CarsXE API key with access to this endpoint."
    - "The vehicle identifier or request inputs required by the YMM Options example."
  verification:
    - "Run one documented YMM Options request and confirm the response is successful and contains the fields described on this page."
  failureModes:
    - symptom: "The YMM Options request is rejected or does not return the expected data."
      resolution: "Check the API key, plan access, supported input format, and the returned status code against the error guide before retrying."
---

# YMM Options
URL: /docs/products/ymm-options
LLM index: /llms.txt
Description: Populate Year, Make, Model, and Variant dropdown menus — one API call returns one layer.
Related: /docs/products, /docs/get-started

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Populate cascading Year/Make/Model/Variant dropdown menus with CarsXE.
Outcome: A YMM Options request returns the documented successful vehicle-data response for the supplied input.

### Prerequisites

- A valid CarsXE API key with access to this endpoint.
- The vehicle identifier or request inputs required by the YMM Options example.

### Verification

- Run one documented YMM Options request and confirm the response is successful and contains the fields described on this page.

### Failure Modes

- The YMM Options request is rejected or does not return the expected data. — Recovery: Check the API key, plan access, supported input format, and the returned status code against the error guide before retrying.
<!-- farming-labs:agent-contract:end -->

Task: Populate cascading Year/Make/Model/Variant dropdown menus with CarsXE.
Related: /docs/products/ymm-options, /docs/products/year-make-model, /docs/products/specifications

Use `/v1/ymm-options` to power cascading dropdowns in your own UI. Each request returns **exactly one list** — `years`, `makes`, `models`, `variants` (combined model + trim display strings, e.g. `"Tacoma TRD Pro"`), or `trims` (shorter manufacturer trim names when you explicitly request `dimension=trims`).

Typical flow: start with no filters to list years → add `year` for makes → add `make` for models → add `model` for variants. One API call per dropdown level.

Need full vehicle specs for a selected year, make, and model? Use [Year Make Model](/docs/products/year-make-model) (`/v1/ymm`) instead.

Endpoint: `/v1/ymm-options`

## Who uses this API

Configurators, quoting tools, and listing forms call this endpoint to populate cascading Year / Make / Model / Variant dropdowns — one list per request, without decoding a VIN.

## Use cases

### B2B

- **Quote and intake forms:** Drive year → make → model → variant selects so staff never free-type a YMM.
- **Parts catalogs:** Load the next dropdown layer as a technician narrows the vehicle.
- **Dealer websites:** Power inventory search filters from the same option lists.

### B2C

- **Consumer configurators:** Let a shopper pick year, make, model, and variant before seeing specs or value.
- **Listing creation:** Guide a private seller through dropdowns instead of a VIN when they do not have one handy.

## Parameters

| Parameter | Required | Description |
|---|---|---|
| `key` | Yes | Your CarsXE API key |
| `dimension` | No | One of `years`, `makes`, `models`, `trims`, or `variants`. When set, the response contains exactly that array when the required filters are present. When omitted, the response layer is inferred from `year`, `make`, and `model`. |
| `year` | No | Filter to a specific manufacturing year. Required when filtering by `model` without `make`. |
| `make` | No | Filter to a manufacturer (e.g. `Toyota`, `Ford`, `Lexus`). Required for `dimension=models`. |
| `model` | No | Filter to a model (e.g. `Camry`, `F-150`, `LX`). Required for `dimension=trims` and for `dimension=variants` unless both `year` and `make` are set (bulk variant list). |

### Automatic response shape (no `dimension`)

Omit `dimension` and the API returns one array inferred from your filters:

| `make`? | `model`? | `year`? | Returns |
|---|---|---|---|
| — | — | — | `years` |
| — | — | ✓ | `makes` |
| ✓ | — | * | `models` |
| ✓ | ✓ | * | `variants` |
| — | ✓ | — | **400** — `year` required when `model` is given without `make` |
| — | ✓ | ✓ | `variants` if that model name maps to one make that year; **400** if ambiguous (add `make`) |

The API never returns more than one layer per response. To populate both a model list and a variant list, make two calls.

### Bulk variant list

Set `dimension=variants` with `year` + `make` (no `model`) to fetch every variant for that make in one flat array — useful for client-side search or filter UIs.

## Billing

Most requests cost **1 unit**.

Exception: `dimension=variants` with `year` + `make` and no `model` costs **1 unit per model**. The response includes `modelCount`, the number of distinct models, which is also the amount billed — with a minimum of 1 unit even when zero models match.

Example: 82 variant strings across 12 models → `modelCount: 12` → **12 units**.

## Example

<CodeGroup title="Populate a cascading dropdown" tag="GET" label="/v1/ymm-options">

```bash
# Step 1 — list years (no filters)
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY

# Step 2 — makes for a year
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d year=2026

# Step 3 — models for a make
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d make=Toyota

# Step 4 — variants for year + make + model
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d year=2026 \
  -d make=Toyota \
  -d model=Tacoma

# Bulk variants for a make + year (billed per model — see modelCount)
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d dimension=variants \
  -d year=2025 \
  -d make=Lexus
```

```js
const apiKey = "YOUR_API_KEY";

async function fetchYmmOptions(params) {
  const query = new URLSearchParams({ key: apiKey, ...params });
  const response = await fetch(
    `https://api.carsxe.com/v1/ymm-options?${query.toString()}`,
  );
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

const years = await fetchYmmOptions({});
const makes = await fetchYmmOptions({ year: "2026" });
const models = await fetchYmmOptions({ make: "Toyota" });
const variants = await fetchYmmOptions({
  year: "2026",
  make: "Toyota",
  model: "Tacoma",
});

console.log({ years, makes, models, variants });
```

```python
import httpx

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.carsxe.com/v1/ymm-options"

def fetch_ymm_options(**params):
    response = httpx.get(BASE_URL, params={"key": API_KEY, **params}, timeout=30.0)
    response.raise_for_status()
    return response.json()

years = fetch_ymm_options()
makes = fetch_ymm_options(year="2026")
models = fetch_ymm_options(make="Toyota")
variants = fetch_ymm_options(year="2026", make="Toyota", model="Tacoma")

print({"years": years, "makes": makes, "models": models, "variants": variants})
```

```bash {{ title: "Response — year=2026&make=Toyota&model=Tacoma" }}
{
  "success": true,
  "input": { "year": 2026, "make": "Toyota", "model": "Tacoma" },
  "variants": [
    "Tacoma Limited",
    "Tacoma SR",
    "Tacoma SR5",
    "Tacoma TRD Off-Road",
    "Tacoma TRD PreRunner",
    "Tacoma TRD Pro",
    "Tacoma TRD Sport",
    "Tacoma Trailhunter"
  ]
}
```

```bash {{ title: "Response — dimension=variants&make=Toyota (fallback)" }}
{
  "success": true,
  "input": { "dimension": "variants", "make": "Toyota" },
  "message": "To receive variants, include a model filter with this make. Models are returned instead.",
  "models": ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"]
}
```

```bash {{ title: "Response — dimension=variants&year=2025&make=Lexus (billed per model)" }}
{
  "success": true,
  "input": { "dimension": "variants", "year": 2025, "make": "Lexus" },
  "variants": [
    "ES 250",
    "ES 300h",
    "GX 550 Premium",
    "IS 300",
    "LX 600 Premium",
    "RX 350"
  ],
  "modelCount": 6
}
```

</CodeGroup>

## Response

### Top-level shape

<YmmOptionsTopLevelShape />

Click `input` or a returned array to expand sample values. For the full interactive reference, try it live in the [API Reference](/api-reference/year-make-model/year-make-model-options).

Each successful response includes `success: true` and exactly **one** of `years`, `makes`, `models`, `trims`, or `variants`. The `message` field is optional guidance when the returned layer differs from what you requested.

<Properties>
  <Property name="success" type="boolean">
    `true` on a successful lookup.
  </Property>
  <Property name="input" type="object">
    Echoes back only the query parameters you submitted.
  </Property>
  <Property name="message" type="string">
    Optional guidance when the returned layer differs from the requested `dimension`, or when explaining what to add next for better results.
  </Property>
  <Property name="years / makes / models / trims / variants" type="array">
    Distinct values for the requested (or inferred) layer. Only one array is present per response.
  </Property>
  <Property name="modelCount" type="number">
    Present only for bulk variants (`dimension=variants` + year + make, no model). Equals the number of distinct models, which is also the amount billed — except a zero-match query, which returns `modelCount: 0` but still bills a minimum of 1 unit.
  </Property>
</Properties>

### variants vs trims

`variants` returns display-ready strings like `"Tacoma TRD Pro"`. `trims` returns shorter manufacturer trim names. Both need a `model` (or disambiguating `year`/`make`) for single-vehicle lookups; only `dimension=variants` accepts `year` + `make` without `model` for a bulk list. For dropdown menus, use inferred responses or `dimension=variants`.

<Note>
  Every request requires a valid, active CarsXE API key and counts toward your **Year Make Model Options** quota — a separate bucket from [Year Make Model](/docs/products/year-make-model). Most calls cost 1 unit; bulk variants (`dimension=variants` + year + make) cost 1 unit per model (`modelCount`).
</Note>

## Errors

| Status | When it happens |
|---|---|
| `400` | Invalid `dimension`, missing required filters, or ambiguous `model` without `make` |
| `401` | Missing or invalid API key |
| `429` | Usage limit exceeded |
| `500` | Could not fetch data |

See the [Errors guide](/docs/guides/errors) for general error handling guidance.

## FAQ

**How is usage billed?**

Most requests cost 1 unit. Exception: `dimension=variants` with `year` + `make` and no `model` costs 1 unit per model. Check `modelCount` in the response — that is the amount billed, with a minimum of 1 unit.

**Why did I get models when I asked for variants?**

You requested `dimension=variants` (or `trims`) with only `make` and no `year`. The API returns `models` for that make and a `message` telling you to add `model` next. With `dimension=variants`, `year`, and `make`, you get variants directly.

**What is the difference between trims and variants?**

`variants` returns display-ready strings like `"Tacoma TRD Pro"`. `trims` returns shorter manufacturer trim names. Only `dimension=variants` accepts `year` + `make` without `model` for a bulk list.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).