Public Inventory Source
The inventory source fetches active dealer inventory from the Stellantis brand public web APIs
(jeep.com, dodge.com, ramtrucks.com, chrysler.com). Its raw and transformed tiers live
in the ai_public code location (the raw sources of ai_public_api.stellantis,
ai_public.sources.stellantis.registry); ai_stellantis holds the consolidated tier and reads
the transformed tables through the public Iceberg IO manager.
Endpoint Pattern
https://www.<brand-domain>/hostd/inventory/getinventoryresults.json
Pagination uses pageNumber (1-based) and pageSize query params. Total record count is read
from result.data.metadata.totalcount in the first page response.
Partitioning by dealer (100k offset cap)
The search returns only the first 100,000 results per query — pages past that offset return
HTTP 500 (an HTML maintenance page, not JSON). A single high-volume modelYearCode (e.g. a Ram
model year code reports ~100k nationwide) therefore cannot be retrieved by one nationwide query.
To capture everything, the fetch partitions by dealer: every vehicle belongs to exactly one
dealer, so the asset queries small comma-joined dealerCodes chunks (DEALER_CHUNK_SIZE, default
10) per model year code and unions them. The result is complete and duplicate-free, with each
query far below the cap. Comma is the only multi-value separator the endpoint honors. The dealer list comes from
the brand's dealer_locator raw asset, so the inventory asset declares two upstreams
(vehicle_data_<brand> for model year codes, dealer_locator_<brand> for dealer codes). With
dealerCodes set, zip/radius are required-but-ignored placeholders.
Required Environment Variables
| Variable | Default | Description |
|---|---|---|
STELLANTIS_INVENTORY_ZIP | US geographic center | Placeholder center ZIP (ignored when dealerCodes is set) |
STELLANTIS_INVENTORY_RADIUS | US nationwide radius | Placeholder radius in miles (ignored when dealerCodes is set) |
STELLANTIS_INVENTORY_DEALER_CHUNK | 10 | Dealers per comma-joined dealerCodes query |
STELLANTIS_INVENTORY_MODEL_WORKERS | 20 | Concurrent request pool size across all (model, chunk, page) requests |
STELLANTIS_INVENTORY_THROTTLE_INTERVAL | 0.20 | Min seconds between requests pool-wide (~5 req/s) |
STELLANTIS_INVENTORY_TIMEOUT | 60.0 | Per-request timeout in seconds (covers connect + read) |
STELLANTIS_INVENTORY_MAX_RETRIES | 3 | Retries per request on transient errors / bot-block pages |
STELLANTIS_INVENTORY_RETRY_BACKOFF | 2.0 | Initial backoff in seconds; doubles each attempt |
STELLANTIS_INVENTORY_MAX_PER_MODEL | (unset) | Cap total records per query (dev/testing) |
Authentication
No credentials required — the endpoint is a public API used by the brand consumer websites.
However, it bot-blocks datacenter IPs (e.g. the production ECS egress) with HTTP 403 while
serving residential IPs normally. Requests therefore go through AkamaiSessionFactory
(ai_http): a curl_cffi browser TLS impersonation that seeds ak_bmsc / bm_sv cookies
from the brand homepage and rotates the session on a block before retrying.
Incentives
Each vehicle has an incentives object, which the transformed tier keeps as a JSON
string. incentives.cash.programs lists the programs included in the price the site shows.
discounted_price is msrp minus their sum (cash.discountAmount).
incentives.cash.extraCashProgramList lists other programs the vehicle is eligible for:
programs the buyer must qualify for (conditional: true), and programs that cannot be
combined with a program in the shown price.
Each program has these fields:
programCodenameincentiveTypeamountpercoffmsrpendDate
The name begins with National or Regional. A program with a nonzero percoffmsrp is a
discount of that percent below MSRP. Its amount is msrp × percoffmsrp / 100 for that
vehicle. A Standalone % Below MSRP program cannot be combined with other cash programs. The
shown price includes the program or the cash programs, whichever gives the larger discount.
The response has no program start date. The same programCode is reissued in later periods
with a new endDate. For a few days after an endDate, the site can still show the
expired programs.
Stellantis Inventory Offers describes the offers built from these programs.
Test fixtures
packages/ai_public_api/tests/data/stellantis/us/inventory_sample.json is a live Jeep search
page for
CUJ202610, trimmed to three vehicles spread across the dealers in the locator fixture. Refresh
with uv run python tests/capture.py; capturing it needs a residential IP, since the same
bot-block applies.
Known Data Quality Issues
Incorrect brand field on Jeep vehicles
The Jeep inventory API occasionally returns a small number of records (~7 per affected day) where
the brand field contains a non-Stellantis value such as "Toyota", "Ford", or "Lexus".
Inspection of the affected records confirms these are genuine Jeep vehicles — VINs start with
1C4 (Chrysler/Jeep WMI) and the Stellantis-internal extImage/intImage fields carry
brand=J. The corrupted brand value originates in the Stellantis backend and is returned
verbatim by the API.
COSY image URL generation requires a valid Stellantis brand. make_cosy_image_urls in
ai_stellantis/cosy.py validates the brand against the set of values accepted by the COSY
generator (StellantisBrand Literal type). Records with an unrecognized brand are written to
the output with null image URLs and a warning is logged; the partition does not fail.
Co-occurring Customer-Preferred Package codes on Wranglers
A vehicle's options string sometimes lists two Customer-Preferred Package codes that cannot
both be installed: on Wrangler trims (model_code starting JLJL or JLJS) the
automatic-transmission CPP (22* / 24*) appears alongside the manual-transmission CPP of the
same trim level (23*). Only one CPP is ever installed, so the manual code is spurious.
Impact: feature_refs is built from options, and the public source has priority 1 for
feature_refs in consolidated inventory. Both codes therefore resolve to feature_ids, and
every downstream consumer (take rates, vehicle attributes, ordering) sees a manual-transmission
package on an automatic vehicle.
ai_dagster.components.FeatureCoOccurrenceTransformedComponent strips the superseded code from
feature_refs in the transformed tier. Rules are (model_pattern, if_present, drop) triples
declared once in ai_public_api.stellantis.option_codes, which both locations'
feature_co_occurrence_removals template var returns; add a rule there when a new pair is found.
Rules match on the vehicle's own model_code, and every trigger is evaluated against the
incoming list, so the rules apply simultaneously.
All three inventory feeds are configured, not just the public one. inventory_api_inventory
builds feature_refs from options; inventory_from_dealerconnect_bq_active and ..._sold
build it the same way from poc_option_codes. Consolidated merges the three by priority
(public 1, dc_active 2, dc_sold 3), so a feed left unconfigured would reintroduce the pair for
any VIN the higher-priority feeds do not carry. In-transit and in-production units never
appear in the public scrape at all, and sold history rows outlive it.
Existing partitions are not corrected. The removal is built into the transformed Iceberg
write, so partitions materialized before it shipped still carry both codes. Consolidated scans a
trailing history_days window (default 365) of transformed partitions, so a vehicle whose last
observation predates the fix keeps the spurious code until those partitions are rebuilt.
Reaching the full window requires backfilling transformed → consolidated → enriched.
The record self-identifies the installed package. mackevisionData.ulp names the upper-level
package, and llp the lower-level one. Across 700 live 2026 Jeep + Ram vehicles, ulp was
populated on every record, always appeared in options, and always appeared in the COSY sa=
list carried by extImage / intImage. The superseded partner, by contrast, appeared in sa=
on none of the 108 vehicles that carried more than one package-formatted code.
Membership in that package set is what the raw record does not carry. Code format is not a
substitute — 553 of the 700 vehicles carry two or more codes matching \d\d[A-Z] (52Z, 51G),
and restricting to the trim letter still leaves non-package codes in scope. The set is named in
the features taxonomy instead: equipment-categories options whose description reads
Customer Preferred Package <code> (category 112, "Do Not Display"), covering both the 2T*
lower-level and 2[234]* upper-level forms.
Production and administrative codes in options
A vehicle's options string lists production and administrative sales codes alongside its
features. Examples are parts modules (X83 "Front End Parts Module"), sales tracking (4EX),
region and sold-to-state codes (875, 931), and price protection codes (3AH). No feature
feed lists these codes in a visible subcategory for any model or model year, so their
references can never resolve to a feature_id, and they count as unresolved in the
consolidated inventory unresolved_refs check.
The inventory sources skip every code in NON_FEATURE_OPTION_CODES
(ai_public_api.stellantis.option_codes) when they build feature_refs. The public source
skips them in PublicInventoryEntity, and the DealerConnect feeds skip them in
DealerConnectInventoryEntity. The options string itself is kept unchanged.
A code joins the list only when a description shows it to be a production, administrative or
parts-module code. Descriptions come from the feature feeds' names or from the DealerConnect
POC pricing matrix. A code format is not a test. Digit-prefixed codes such as 24F are
packages, and X9, X9B and X9H are features although X83 is a parts module.