Battery models, versions and units
How BatteryPass separates the product, its technical states and the individual batteries, and where each value lives.
BatteryPass keeps product data on three levels. Data that every battery of a product shares is maintained once, on the model version; data that differs per battery lives on the unit. Each unit gets its own passport, built from both levels when it is published.
flowchart LR M["Battery model: name, SKU, GTIN, category"] --> VA["Model version A: superseded"] M --> VB["Model version B: approved"] VA --> U1["Unit SN-000184"] VB --> U2["Unit SN-000417"] U2 --> P["Passport of SN-000417"]
The three levels
| Level | What it is | Main fields | Read with |
|---|---|---|---|
Battery model (BatteryModel) | The commercial product | name, sku, gtin, category, archived_at | listBatteryModels, getBatteryModel |
Model version (ModelVersion) | One technical state of the model, for example after a cell change | version_label, effective_from, status, unit_count, approved_at, registry_version | listModelVersions, getModelVersion |
Unit (Battery) | One physical battery with a serial number | serial_number, model_version_id, manufacturing_date, facility_id, battery_status, passport_status | listBatteries, getBattery, exportUnits |
The category of a model (ev, lmt, industrial, stationary, industrial_without_bms) decides which
fields the registry requires for its batteries.
Model version status
A model version has a start date, effective_from, and a status:
status | Meaning |
|---|---|
draft | In preparation. Units on a draft version cannot be published. |
approved | The current technical state. A model has at most one approved version; a reviewer approves it in the portal. |
superseded | Replaced by a later approved version. It stays readable and keeps its units; their published passports are not changed. |
A version has no end date: it applies from its effective_from until a later version takes over. When a unit
is created in the portal or by the spreadsheet import without a named version, BatteryPass assigns the version
in force on the unit's manufacturing date: the one with the latest effective_from on or before that date,
preferring approved and superseded versions over drafts. Approving a new version moves no existing unit. Members move units to another version in the portal after a change-impact
preview, and a published passport of a moved unit becomes update_needed
(Passports).
Which values live where
The field registry assigns every field a level. Read it with
getRegistrySchema: each field has level set to
model or unit.
| Level | Typical fields | Values | Completeness |
|---|---|---|---|
| Model version | Manufacturer, mass, warranty, chemistry and composition, hazardous substances, carbon footprint, due diligence, circularity, performance ratings, labels and the declaration of conformity, e.g. performance.nominal_voltage, materials.battery_chemistry | listModelVersionValues | getModelVersionCompleteness |
| Unit | Serial number, manufacturing date and place, battery status, date of putting into service, and the condition data, e.g. identification.serial_number, condition.capacity_fade | listBatteryValues | getBatteryCompleteness |
A few registry fields are attributes of the model or unit itself rather than separate values: the product
name, SKU, GTIN and category of the model; the serial number, manufacturing date, facility, battery status and
date of putting into service of the unit. You read them on BatteryModel and Battery.
A unit's completeness response also carries the summary of its model version (model_version), so one call
tells you whether either level still blocks publication.
Identifiers
| Identifier | Where | Rules |
|---|---|---|
| GTIN | On the battery model | Accepted with 8, 12, 13 or 14 digits and stored as GTIN-14 with a valid check digit |
| Serial number | On the unit | Letters, digits, -, / and ., at most 50 characters, unique per model |
| GTIN and serial number together | The key of the unit | Unique across all organisations; the GS1 Digital Link encodes exactly this pair |
Once the identifiers are locked (for label printing before publication, or at the first publication),
identifiers_locked_at is set and the serial number and the model's GTIN can no longer change.
Second life: a repurposed, reused or remanufactured battery is a new unit. It names the original in
predecessor_battery_id (the original lists it in successor_battery_ids) and gets its own passport.
Reading the catalogue
List the versions of a model, then the units of one version:
curl -s "$BATTERYPASS_URL/api/v1/battery-models/$MODEL_ID/versions" \
-H "Authorization: Bearer $BATTERYPASS_API_KEY"
curl -s "$BATTERYPASS_URL/api/v1/batteries?model_version_id=$VERSION_ID&limit=200" \
-H "Authorization: Bearer $BATTERYPASS_API_KEY"listModelVersions returns at most 200 versions, newest effective_from first, without a cursor.
listBatteries is ordered by serial number and paged with limit and cursor
(Pagination); it also filters by battery_model_id, passport_status,
serial_prefix and import_id.
The API reads the catalogue; it does not create or change it. Members create models, versions and units in the portal or with the spreadsheet import, and reviewers approve model versions.