# Integration API v1 field catalogue

The reviewed scopes of an integration are the outer boundary. An active user
grant may reduce that set further. Unknown fields are rejected on ingest and
removed again at operator egress. A field appearing in BOT's internal data does
not make it part of this contract.

The downloadable JSON Schemas are normative for JSON types and shape. This
catalog explains meaning and privacy boundaries. Fields can be omitted when BOT
has not received an allowed value; an explicit `null` means the allowed value is
currently unknown. Consumers must ignore newly documented optional fields but
must not accept unknown fields when validating uploads or generating webhook
payloads.

All date-times are ISO 8601/RFC 3339 UTC values and all date-only fields use
`YYYY-MM-DD`. Country values are upper-case ISO 3166-1 alpha-2 codes. Resource
identity always comes from the envelope's `resource.id`; it is random and scoped
to one integration. Do not require or derive an identifier inside `data`.

Some compatible upload versions can represent configuration, location, dates,
or milestones either as top-level fields or in the correspondingly named nested
object. Consumers must support the forms admitted by the JSON Schema. The v1
contract does not assign a general precedence to conflicting duplicates, so do
not silently merge contradictory values. `expected_delivery` is the
authoritative human-readable delivery-window text; parsed start/end dates remain
separate, nullable interpretations.

## Order snapshot

The `orders.read` scope may expose:

- identity-neutral vehicle/order description: `model`, `variant`, `factory`,
  `factory_code`, and unique `option_codes` (the codes are configuration data,
  never a VIN or provider identifier);
- resolved `configuration`: `color`, `wheels`, `interior`, `autopilot`, and
  nullable boolean `tow_hitch` (compatible top-level fields can also occur);
- `delivery_center` and two-letter `country`/`country_code`, either top-level or
  in `location` where supported;
- `order_date`, `reservation_date`, `order_booked_date`,
  `delivery_appointment_date`, `expected_start_date`, `expected_end_date`, and
  authoritative text `expected_delivery`, plus the non-personal availability
  milestone `parts_catalog_available_on`, either top-level or in `dates` where
  supported;
- nullable milestone flags/timestamps: `vin_assigned`, `vin_assigned_on`,
  `vehicle_built`, `vehicle_built_on`, `in_production_at`,
  `ready_for_pickup_at`, `in_transit_at`, and date-only `delivered_date`, either
  top-level or in `milestones`;
- `status` and `last_delivery_window_change_at`.

Individual `status` is a forward-compatible source value, not the closed set
used by the statistics endpoint. Do not fail an entire sync because a new
status string appears.

`model` is the vehicle family (for example `Model Y`). `variant` is the
specific trim (for example `Long Range AWD`) and must not merely repeat
`model`. BOT resolves an empty or base-only variant server-side from its
reviewed option-code catalogue. Integrations should consume the returned
`variant` and must not invent their own trim mapping from an option code.

If an uploaded `variant` is itself one of the order's raw option codes, BOT
also treats it as unresolved. Missing `color`, `wheels`, `interior`,
`autopilot`, `tow_hitch` and their `configuration` equivalents are completed
server-side only from unambiguous entries in BOT's reviewed public option-code
catalogue. Existing human-readable values remain authoritative. Ambiguous or
unknown mappings stay `null`; integrations should not guess them.

`delivery_center` is always present at the top level of an order response. It
is either the app-provided public pickup center, an unambiguous exact match from
BOT's public delivery-center catalogue, or `null` when BOT has no trustworthy
public value. Address-like or unmatched free text is never used as a fallback.

With the separately reviewed `shipping.read` scope, an actively granted order
may additionally contain minimized `vessel`, `voyage`, `loading_port`,
`destination_port`, `estimated_departure_at`, `estimated_arrival_at`, and up to
2,000 shipping events. An event can contain `event_type`, `port`, `country`,
`occurred_at`, `observed_at`, and `status`. Shipping never contains a VIN or
serial number. Without the effective `shipping.read` grant, the entire object
is removed even if it exists internally.

## Order history

`orders.history.read` exposes an append-only, cursor-paged sequence. Each item
contains `sequence`, allowlisted `field`, `operation`, minimized old/new value,
`event_at`, `observed_at`, and `data_quality`. `history_complete=false` means the
app has not yet uploaded and closed the full initial history. The marker changes
only after the explicit completion operation.

`sequence` is monotonic within one resource history, not across resources.
`event_at` is the time attributed to the underlying change; `observed_at` is
when BOT observed/received it. `data_quality` is descriptive and
forward-compatible. The allowed operations are `set`, `unset`, `append`, and
`replace`. Apply pages in sequence order, retain `null` as a meaningful
old/new value, and never claim the history is complete merely because
`has_more=false` while `history_complete=false`.

The changed `field` is restricted to a path from the corresponding allowlisted
snapshot. Array changes may be indexed without exposing an identity: for
example, `option_codes[0]` changes exactly one option code and
`shipping.events[3].status` changes one permitted shipping-event value. Both
bracket indexes and their canonical dot-index equivalent can be consumed.
Indexes range from 0 through 1999. Unknown paths and paths to VINs, true order
numbers or any other forbidden data are rejected at upload and removed again at
egress. `option_codes` and every indexed option-code history change are
available for both orders and stock vehicles when the corresponding snapshot
and history scopes are active.

## Stock vehicle snapshot and history

For an individually selected stock vehicle, `vehicles.read` may expose:

- identity-neutral description: `model`, `variant`, `factory`, `factory_code`,
  unique `option_codes`, resolved `configuration`, `car_type`, `trim_badging`,
  `wheel_type`, `spoiler_type`, `exterior_color`, `driver_assist`,
  `headlamp_type`, `rear_drive_unit`, and `efficiency_package`;
- operating/feature state: `state`, `in_service`, `has_air_suspension`,
  `has_seat_cooling`, and `smart_summon_available`;
- battery/range: `battery_level`, `usable_battery_level`, `battery_range`,
  `battery_range_km`, `ideal_battery_range`, `ideal_battery_range_km`,
  `estimated_battery_range`, and `est_battery_range_km`;
- charging: `charging_state`, `charge_rate`, `charger_power`,
  `charge_power_kw`, `charger_voltage`, `charger_phases`,
  `charger_actual_current`, `charge_limit_soc`, `time_to_full_charge`,
  `charge_energy_added`, `charge_miles_added_rated`, `conn_charge_cable`,
  `charge_port_type`, `charge_port_latch`, and `charge_port_color`;
- distance/software/tyres: `odometer`, `odometer_km`, `software_version`,
  `software_update_version`, and `tpms_pressure_fl/fr/rl/rr`;
- minimized battery hints: `battery_pack_hint`, `battery_family_hint`,
  `battery_capacity_kwh_hint`, `battery_detection_source`, and
  `battery_detection_confidence`;
- observation times: `last_updated_at` and `observed_at`.

Names containing `_km`, `_kw`, or `_kwh` carry kilometres, kilowatts, or
kilowatt-hours respectively. Battery/SOC percentages are in the inclusive
0–100 range; `battery_detection_confidence` is 0–1. The v1 schema does not make
a unit guarantee for legacy unsuffixed numeric fields such as `battery_range`,
`odometer`, `charge_rate`, `time_to_full_charge`, or tyre pressure. Prefer the
explicitly suffixed form when present and do not invent a conversion for an
unsuffixed value.

`vehicles.history.read` uses the same history envelope as order history.
Identical received states are deduplicated; an actual allowlisted change is not
discarded. Vehicle snapshot and history access are separate scopes.

`option_codes` is deliberately part of the documented order and vehicle
contract so an authorized integration can resolve configurations and build
useful aggregate analyses. It is not available from a resource the user did not
select, and it never weakens the separate statistics opt-in or minimum-cell
rules.

## Scope combinations

- `orders.read` is required for order snapshots/sync upserts.
- `orders.history.read` is required for order history and does not add shipping.
- `shipping.read` only adds the minimized shipping subtree to an already
  readable, actively granted order.
- `vehicles.read` is required for selected stock-vehicle snapshots/sync upserts.
- `vehicles.history.read` is required for selected stock-vehicle history.
- `statistics.orders.read` returns only fixed preaggregated generations; it does
  not grant any individual order.
- `revocations.ack` permits deletion acknowledgements and grants no read access.

### Order statistics vocabulary

Every returned cell contains `dimensions` and `value`. The metric name is the
key containing the cell array. Cells below the minimum cohort size are omitted,
so breakdowns must never be summed to infer a total.

| Metric | Dimension keys | Value |
|---|---|---|
| `orders_total` | `country` | Integer count of all opted-in orders in the country |
| `by_model_variant_status` | `country`, `model`, `variant`, `status` | Integer count |
| `vin_assigned` | `country` | Integer count |
| `vehicle_built` | `country` | Integer count |
| `delivery_within_30_days` | `country` | Integer count |
| `delivery_within_60_days` | `country` | Integer count |
| `average_order_age_days` | `country` | Number of days |
| `daily_vin_assignments` | `country`, `date` | Integer count |
| `daily_builds` | `country`, `date` | Integer count |
| `by_delivery_center` | `country`, `delivery_center` | Integer count |
| `by_color` | `country`, `color` | Integer count |
| `lead_time_order_to_vin_days` | `country`, `percentile` | Number of days |
| `lead_time_vin_to_delivery_days` | `country`, `percentile` | Number of days |

`status` is one of `open`, `booked`, `in_production`, `ready_for_pickup`, or
`in_transit`; `percentile` is `p25`, `p50`, or `p75`; and `date` is an ISO
`YYYY-MM-DD` calendar date. `orders_total` is evaluated directly against the
same minimum cell size and does not depend on which breakdown cells survive
suppression.

The effective scopes returned by `GET /v1/capabilities` are the maximum for that
certificate/environment. A user's resource grant can narrow them further.

## Always forbidden

The API never exposes real VINs or order numbers; BOT/Tesla account identifiers;
names, email, phone, address or other contact data; financing, payment or profile
data; Tesla IDs, access tokens or credentials; raw Tesla/EPC responses;
application version/platform; parts/equipment summaries in the reference profile;
GPS/calendar/vehicle name; or door, window, lock and other presence/security
state. Forbidden values are excluded from snapshots, histories, aggregates,
webhooks, logs and error documents.

The random `connection_id`, `ord_*` and `veh_*` values are scoped to one
integration and cannot be correlated with another integration's identifiers.
They are still authorization-bound application data: do not expose them in URLs,
analytics or logs beyond what the integration needs to operate.