API reference

The bundled classifier's version, so its suggestions can be told apart later.

[x1, y1, x2, y2] in original pixels, x2 > x1, y2 > y1.

[x, y] of the crop's top-left corner in composite pixels.

What unit_value is per — kilogram, litre or piece (kom). The parser normalises /100 g and /100 ml to these.

ISO 4217 — HR → EUR, RS → RSD, BA → BAM.

Firestore document id.

References tenants/{tenantId}/locations/{location_id}.

Firebase uid of the capturing user; references users/{uid}.

Last time an image was added; drives "resume visit".

Denormalised count of the images subcollection. Image documents are created by clients directly in Firestore, where the API has no hook, so this is maintained by a Firestore trigger in functions (onImageCreated / onImageDeleted). Clients must not set it.

Images whose state is finished or warning. Maintained by the vision service inside the analysis transaction, by read-modify-write on this document — never by a count query.

v1.24. The shelf length the rep measured by hand, in centimetres, for a visit in a tenant with Tenant.measurement. Client-owned: the visit's owner or a tenant admin sets or clears it, never on a locked visit. When present it replaces the measured length as the visit's measurement.shelf_cm; the measured one stays in measurement.measured_cm and both are shown. The legacy capture build kept this inside stats.

v1.24. The visit's shelf length and positions against what the location expects. Server-owned: functions recomputes it whenever a photo of the visit changes its subject, guerilla or measurement, is added or removed, or manual_shelf_cm changes. Absent in tenants without Tenant.measurement.

v1.17. A locked visit is closed to review edits — the legacy app's Task.locked ("Item 7a"), used to freeze a visit once it has been checked. Corrections to its images are refused with 403 permission_denied, and the rules refuse a change to an image's count_region while it is set. Only tenant_admin and above may set or clear it; captures and server analysis are unaffected.

v1.8. Every node, inclusive, on the path from a hierarchy root down to where this visit sits: the union of the capturing user's sales_node_id ancestor chain and the location's customer_node_id ancestor chain. Server-owned — clients must not set it, and firestore.rules refuses a write that touches it.

It exists so row-level visibility is one set-membership test in rules (sales_node_id in visible_node_ids) and one array-contains in a query. The alternative — prefix-matching the materialised path — cannot be expressed safely in rules, because building a regex out of caller-controlled data is how a scoping check turns into a scoping bypass.

Maintained by functions on create, and rewritten by the re-parent backfill. Empty means the visit is not placed in any hierarchy; whether that is readable is decided by Tenant.visibility_scoped, never guessed.

The sum of image_analysis.measurement.total_cm over the visit's shelf photos. Null until one of them has been measured.

A copy of Task.manual_shelf_cm as it stood at the rollup.

The length the visit is judged by: manual_cm when the rep gave one, else measured_cm.

rack photos that are not guerilla: the paid ones.

rack photos with guerilla: true.

The location's expected as it stood at the rollup, so a visit is judged against what it was shown. Null when the location expects nothing.

Measured shelf length per row, in centimetres.

New in v1. Denormalised parent task id, stamped at capture. Redundant with the document path, but required so that collectionGroup('images') queries — which the analytics dashboards rely on — can resolve the task without a second read.

New in v1. Denormalised from the parent task, stamped at capture. The legacy schema omitted it, forcing the web app to approximate per-store metrics by nearest-GPS-within-500m, which broke per-store accuracy. Stamping it here is the fix.

Display name, usually the original filename.

Cloud Storage object path. The uploader stamps customMetadata.image_object_reference on the object with this document's full Firestore path, which is the handoff signal the Storage trigger reads.

Full Firestore path of this document; mirror of the object metadata.

Android MediaStore id; local bookkeeping only.

Device-local content:// URI. Written by the capture client so the offline queue can find the file; meaningless server-side.

New in v1.1. Minted by the capture client at shutter and written here and to the Storage object's customMetadata. Nullable only so that a trace failure can never block a capture; a null value means this image's history cannot be reconstructed across modules.

For burst: Storage paths of the originals in capture order. firebase_storage_path is the first of them.

Server-written for burst: the assembled virtual-shelf composite. Review UIs display this in preference to firebase_storage_path when present.

v1.11. How a multi-frame capture became one picture. manual: the rep lined the frames up by hand on the phone (roadmap §10.1); the composite is firebase_storage_path, the frames are burst_originals and burst_layout says where each one sits. auto: the server assembled it (roadmap §10.2). Null for a single image or a legacy stitched one that kept no originals.

v1.11. One entry per burst_originals element, same order. Present when assembly is manual; the server may fill it for auto. A consumer that has the originals and the layout can re-render the composite exactly, which is what lets vision project per-frame detections into composite coordinates without re-aligning anything.

Server-written when state is error; human-readable.

v1.24. What the photo shows, in a tenant with Tenant.measurement. Client-owned: set at capture and changeable afterwards by a tenant member, never on a locked visit. Null or absent reads as shelf.

Every photo is analysed the same way whatever its subject, so a change needs no second analysis; the subject decides what counts. A shelf is measured and its facings count. A rack or a recipe_rack is one position in Task.measurement and its facings are kept. Nothing found on a graphics photo counts as a product: stats, facts and shares skip it.

v1.24. Whether subject is the on-device classifier's pick left as it was (model) or a person's choice (human).

v1.24. What the on-device classifier proposed at capture and how sure it was. Kept when a person chooses otherwise: the pair is the training signal for the next classifier.

v1.24. On a rack: a position that is not paid for, as the rep marked it. Counted in guerilla_racks, not in racks. Meaningless, and read as false, on any other subject. Client-owned like subject. Absent means false.

Embedded canonical analysis; absent until one is accepted. A copy of the winning document in the analyses/ subcollection, which holds every submission (with superseded set) as audit trail and training signal.

v1.8. Every node, inclusive, on the path from a hierarchy root down to where this visit sits: the union of the capturing user's sales_node_id ancestor chain and the location's customer_node_id ancestor chain. Server-owned — clients must not set it, and firestore.rules refuses a write that touches it.

It exists so row-level visibility is one set-membership test in rules (sales_node_id in visible_node_ids) and one array-contains in a query. The alternative — prefix-matching the materialised path — cannot be expressed safely in rules, because building a regex out of caller-controlled data is how a scoping check turns into a scoping bypass.

Copied from the parent task, so a collectionGroup('images') read can be scoped without a join. Maintained by functions on create, and rewritten by the re-parent backfill. Empty means the visit is not placed in any hierarchy; whether that is readable is decided by Tenant.visibility_scoped, never guessed.

v1.14. Keep this image past the tenant's retention.images_days. Set by a tenant admin from the review screen ("keep"), and by the server when a cutout of the image is flagged for_training — a labelled example is worth more than the window. The retention job never removes a held image and never clears the flag; storage class still cools with age. Absent means false.

v1.21.0. When a person said "I have looked at this photo and it is right as it stands". Without it the only way to take a photo off the to-check list was to name every box on it, and a shelf of competitor products nobody will ever name stayed "needs a look" for good.

Client-owned, set together with reviewed_by: a tenant member writes their own uid and the server's time, or clears both — the rules accept nothing else, and nothing at all on a locked visit. It is a statement about the analysis the person saw, so the server clears both when a model analysis becomes canonical after it (a retry, a newer model). A person's corrections leave it alone: they are the review, not a reason to ask for another one.

Review clients show such a photo as checked whatever its boxes say. It changes no state, no counter and no fact row.

v1.21.0. Firebase uid of whoever set reviewed_at. Null exactly when reviewed_at is.

One entry per detected object. May be empty (nothing on the shelf).

Pixel width of the analysed image.

Pixel height of the analysed image.

Total objects, all detection classes. Derived from image_analysis_objects; the server recomputes it on write and ignores any client-supplied value.

Objects with detection_class: product. Server-derived, as above.

Recognition model identifier, e.g. nelt-detector.

Model version, compared during reconciliation. Exactly one of two formats: semver MAJOR.MINOR.PATCH (compared numerically per component — 1.10.0 > 1.9.0) or an ISO date YYYY-MM-DD (compared as a date). Anything else is 400. Across formats a date is treated as newer than any semver: dates are how the training pipeline stamps promoted models, semver is legacy.

Wall-clock seconds spent on inference.

True when this analysis lost reconciliation and is retained only for audit. The canonical analysis on an image is never superseded. Server-derived; ignored on input.

Server-derived. SHA-256 of the submission with server-derived fields removed and keys sorted — the idempotency key for PUT. Ignored on input.

v1.24. The shelf length the tenant's own products occupy on this photo, for tenants that measure (roadmap §12). Server-derived from the objects on every canonical write — a correction re-measures — ignored on input and left out of submission_hash. Null or absent where the tenant does not measure. Computed whatever the photo's subject; only a shelf photo's length enters Task.measurement.

The sum of the spans' lengths. Null with method: none.

The board, normalized: where the row's facings stand.

Left to right; what a review UI draws as rulers.

Own bottom-layer facings in the row.

How many of them set the row's scale.

The sum of the rows that could be measured. Zero when the photo shows none of the tenant's own products; null when it shows some and none could be measured.

Pixel coordinates. Derived, not authoritative — a convenience mirror of the normalized box against ImageAnalysis.width/height. Normalized coordinates are the contract; consumers that resize or re-crop must recompute pixels rather than trust these. The server recomputes all four on write and ignores client-supplied values. Always present on stored documents and in responses — the current review UIs render from them — and nullable only on input.

Detector class index as emitted by the model, kept as provenance. Its meaning is per model: the shared product detector emits 0 = product, 1 = out_of_stock, while pliva's emits 0 = shelf, 1 = row, 2 = product. The mapping to detection_class is tenant configuration in the vision service, and classes that have no contract meaning (shelf, row) are dropped before emission. Never interpret this index directly.

Classifier result: the numeric id of the recognised tenants/{tenantId}/products/{class_id} document. Null when the object is out_of_stock, or when the classifier declined.

Denormalised product name at analysis time. Display convenience — class_id is authoritative; renaming a product does not rewrite historical analyses.

Pack size, e.g. 0.5L. Catalog-derived, not a model output: no classifier has ever emitted it. The server fills it from Product.sizes when the recognised product has exactly one size; otherwise null and clients may derive it themselves.

True when a human added, moved or re-labelled this object. Marks high-value training data. Since v1.3 this is derived from provenance (any human entry) and kept for older readers.

v1.3. Stable identity of this object across analyses and corrections — the thread that lets a cutout be found from the catalog and its history be followed. A uuid4, minted by the server the first time an object exists (model detection or human add) and preserved by relabel and move. Nullable only on input; always present on stored documents and in responses.

v1.3. Who produced the box and who produced the label. Server filled; ignored on input.

v1.23. The reading of a price_tag; null on a tag nobody has read and on every other class. Validation on write: present only with detection_class: price_tag (400 otherwise).

v1.23. On a price_tag: the object_ids of the product objects on the same image this tag prices — the facings in the row the tag's printed name matched (the row directly above the tag or the one below it), or the row above when the name matched neither. Empty on a price image, where there are no facings, and on every other class. A person corrects it by editing the object.

v1.23. On a price_tag: the catalog product the tag prices, from its printed name — on a price image the only link. Null when the name matched no product; a person may set it through a correction. Reporting attaches the price to this product.

v1.24. On a product in a tenant that measures: whether this facing shows its true width (frontal, whole) and so may set the scale of its row. Null or absent: not assessed — a box a person drew or moved, a product the classifier did not name, a tenant that does not measure. Server-owned: ignored on input, carried through relabel, cleared by move. The legacy stack's referent_value.

Firebase uid when kind is human.

Null for out_of_stock and for objects nobody has labelled.

Cloud Storage object to analyse. Bucket-relative (tenant bucket implied) or a full gs:// URI; must belong to the request's tenant.

Override the tenant's configured model. Omit for the default.

Pin a model version. Omit for the tenant's current version.

Recovered by onImageUploaded from the Storage object's customMetadata and forwarded. This is the single link that keeps device-side and server-side records on the same trace — if it breaks, everything downstream is orphaned.

Part of the idempotency key (image, model_version).

Retry counter. The retryFailedAnalyses scheduled function re-enqueues failed jobs and increments this. Retries keep the original trace_id, so the whole retry history stays on one trace.

Populated only when state is failed.

Present when this submission fulfils a :analyze job.

When the device produced this result. Distinct from analysis.analyzed_at for offline submissions that sync later.

The originating capture's trace. An offline device submission may arrive days later and still join its own capture records.

True when the submitted analysis became canonical. False when an existing analysis won reconciliation — the submission is retained with superseded: true and canonical holds the winner.

Human-readable explanation when accepted is false.

Firebase uid of the operator making the correction.

analyzed_at of the analysis the operator was looking at. When it no longer matches the canonical analysis the server responds 409 rather than applying edits to a version the operator never saw. Null skips the check — "apply to whatever is current".

Compared at millisecond granularity. A Firestore snapshot reaches a browser or an Android client as a Date, which is millisecond-precision, so an operator can never echo back the microseconds a server-side timestamp would carry. The server mints analyzed_at truncated to milliseconds and compares at that granularity; requiring microsecond equality would make every correction from a snapshot-driven UI conflict.

v1.3, preferred. The object to edit. When present it wins over object_index.

Position in the pre-batch array. Required for remove, relabel and move when object_id is absent; omitted for add. Kept for v1.2 clients; new clients send object_id.

The new or replacement object. Required for add and move. For relabel, only class_id, class_name and detection_class are read.

Cloud Storage path of the reference pack shot (catalog_images/{tenantId}/products/{productId}.jpg, v1.12). A tenant admin sets it from the web catalog; the catalog rendering of a shelf draws it in place of the detected object.

Denormalised category name; category_id is authoritative.

Denormalised subcategory name; subcategory_id is authoritative.

Hex colour used to tint this product's boxes in review UIs.

Pack sizes this SKU ships in; matched against ImageAnalysisObject.size.

Client's own article code; distinct from sku and barcode in some catalogs.

Physical pack dimensions. Present in the pliva, pampers and violeta catalogs and edited in the web catalog UI; the input to any shelf-measurement feature.

v1.3. The product-hierarchy leaf for this SKU. brand_id, category_id and friends are denormalised from its ancestors.

True for entries created ad hoc by an operator rather than imported from the client's master catalog. Excluded from share-of-shelf denominators until curated.

Full legal or marketing name; name is the short display form.

Filename of the logo asset in the brand bucket.

Client's own store code; the join key for external reporting.

ISO 3166-1 alpha-2.

Key Account Group — the retail chain this store belongs to.

v1.3. The customer-hierarchy node this store is (or sits under). kag_name is a denormalised copy of an ancestor's name.

v1.24. What this store is supposed to have, for tenants with Tenant.measurement. Null or absent: nothing is expected and no visit here is judged. Written only through PUT …/locations/{locationId}/expected and the import script.

Centimetres of shelf the client's own products should occupy.

Paid racks. A guerilla rack does not count towards it.

Racks the client knows it has here without paying for them.

Cloud Storage prefix for this company's assets.

Document id; equal to firebase_id.

Firebase Auth uid.

v1.19.0. Access to ShelfPro Labeling (label.theshelfpro.com), the internal labelling tool, which signs people in with the same Firebase account. admin creates projects and rounds and assigns them; annotator sees only what is assigned to them; null (the default) means no access. Independent of role, which is the tenant role: a platform_admin is a labeling admin whatever this says, and a tenant's contributor may be an annotator. Set by a platform admin; never by the user.

The invitation this account redeemed, so "who let this person in" resolves to a document with an inviter on it. Replaces the v1.6 access_code, which recorded only the string a user typed.

Client build the user last signed in from; support diagnostics.

v1.22.0 — who writes it. The installed Android app, to its own document (the rules let a user update their profile outside the server-owned fields), whenever the stored pair differs from the build that is running. Only builds people install write it: a developer's debug build against production does not. With ClientRequirements.min_version_code it answers "who is still on a build we are about to stop accepting".

The same build as people read it, e.g. 0.1.2. Written with version_code.

v1.3. The sales-hierarchy node this user occupies. Also the root of what they may see in reports.

Firestore path of the image document.

v1.25. The visit's visible_node_ids, copied by the indexing trigger (and rewritten by the visibility backfill) so a cutout is readable exactly when its visit is: the objects/ rule applies isInVisibleSubtree to the record itself, and a scoped client lists with array-contains on it (or user_id == for its own). Empty on a record indexed before v1.25 until the backfill has run — which is why the backfill goes before the rules in a rollout.

Null means unclassified — the review inbox queries on it. On a price_tag record (v1.23) the field is absent, not null, so product_id == null keeps returning products only: a tag has no product of its own, and must not land in the inbox.

v1.23. Copied from the object; the gallery shows the reading on the cutout.

v1.23. Copied from the object. The gallery's "Prices" tab lists a product's tag cutouts by it, newest first — apart from the product's own cutouts, which stay under product_id.

The image's created_at — when the shelf looked like this.

True once a later canonical analysis no longer contains this object.

Free tags such as for_training or not_this_product, set from the gallery.

The capturing user, as on the visit.

Days a shelf photo is kept after its capture; null keeps forever.

The person's Firebase uid; null for the server.

The subject's id as a string (a catalog id, a Firestore document id, a uid).

The Firestore path of the subject when it is a document, so the page can link to it.

How the subject was called at the time — a product's name, a location's name, a person's email. Kept here because the subject may be renamed or gone.

Which server wrote it — the api route, or a trigger reflecting another service's write.

One line in the server's words, for a log reader; the page shows the translated action, not this.

The capture's trace when the change is image-scoped (a correction), so it joins the trace.

The identity acceptance is checked against. Required on every invitation, including manual — a link that is not bound to somebody is a bearer secret again.

Contact detail only — seeded onto the user document. It is never an authentication factor: SMS delivery was dropped in v1.7.1.

Display name to seed the user document with.

Where in the sales hierarchy the new user sits (v1.3).

Firebase uid of the inviter. "Who let this person in" is answerable.

The account that redeemed it — not necessarily a pre-existing one.

Contact detail only; never an authentication factor.

Present only for channel: manual. Shown once.

Position in the submitted array.

The raw token from the invitation link. Compared against a stored hash.

Null for a root. A hierarchy may have several roots.

The client's own code for this node (SAP, ERP); the import join key.

Open key-value for filters (channel, format, …). Never structure.

Reserved for as-it-was-then reporting; unused in v1.3.

Null marks a root.

Default true — an import that cannot be previewed will not be trusted.

Mark nodes absent from the payload inactive rather than leaving them. Never deletes: a node with history behind it stays, so old reports keep resolving.

Nodes whose parent changed — the expensive ones, since a move rewrites paths beneath.

Unknown parent_code, a cycle, or a duplicate code. A dry run reports every error; a real import applies nothing when any row errors.

Display label, in English. English is required and is the fallback for every locale, so a KPI always has a label even where no translation exists.

v1.9. Optional per-locale labels, keyed by language tag.

Localising here rather than in each client is deliberate: the matrix on screen and the Excel export are produced by different code, and a label held client-side drifts from the workbook the moment a KPI is renamed. One source, both surfaces.

v1.9. Per-locale descriptions; description is the fallback.

Which fact table it reads.

A display hint, e.g. 0.0% or #,##0.

For ratio.

Hierarchies whose filters the denominator drops, when denominator_scope is ignore_hierarchies. Row grouping still applies to the numerator; only the denominator widens.

Stable slug; what the matrix reports as the group key. Renaming a period keeps its id, so a saved view does not lose its rows.

Display label, in English. See name_i18n.

Optional per-locale labels, keyed by language tag. name is the fallback and the only required one.

What the client calls this shape. Purely descriptive — grouping uses period, and the derived quarter/half/year grains come from fiscal_year_start_month, never from this field. It exists so a UI can offer "the quarters" without pattern-matching names.

Inclusive. Must not be before start_date.

Node ids that are open, as full paths from the first row axis (n_zagreb, n_zagreb/n_konzum). Absent means only the top level.

Children returned per expanded node.

Null exports the depth the query's expand describes.

Null means no facts matched — distinct from zero.

Returned for ratio KPIs so a client can re-aggregate a subtotal itself without asking again, and so a share of 0/0 is visibly not a share of 0/100.

Address of this row within the matrix, e.g. n_zagreb/n_konzum.

Depth in the row axis, not in the hierarchy.

Which row axis produced this level — a hierarchy kind or a time grain.

Set when columns pivot, e.g. 2026-07.

Column keys in display order when the column axis pivots.

Descriptors for the requested KPIs, so a client can format without a second call.

Grand totals over everything the caller may see, after filters.

The time window the query actually ran over. A request that names no bounds gets a default window rather than an unbounded scan, and a reader comparing two numbers needs to know they cover the same period. Never null on a served response.

True when a node had more children than limit. Never silently partial — a matrix that quietly drops rows is worse than one that says it did.

front, back, side, top, on_shelf — free text from the capture flow.

The (possibly write_in) product this documents; null for a category sweep.

Usually a fixture or shelf node; may be a store.

Left-to-right order on the shelf when known.

A customer-hierarchy node. The grant covers its whole subtree.

Firebase uid of the admin who granted it.

For a temporary cover arrangement. Null never expires.

Overrides the shared bucket when a tenant has its own.

Set by a tenant admin through PUT …/retention (v1.26); the document itself is server-owned.

How this tenant names time.

Two mechanisms, because clients need both. fiscal_year_start_month is a rule: set it to 4 and every quarter, half and year shifts, for every year, past and future, with nothing to maintain. periods is a list: explicit dated ranges with names of the client's choosing, for the boundaries no rule produces.

v1.8. When true, a tenant member may read a visit only if they captured it, they administer the tenant, or their sales_node_id appears in the visit's visible_node_ids. When false, any tenant member may read any visit in the tenant, which is the v1.7 behaviour.

The flag exists because the two alternatives are both wrong. Making the check unconditional locks every existing tenant out of its own data until a backfill finishes. Treating an empty visible_node_ids as "unrestricted" fails open, and a half-populated backfill would then silently widen access while appearing to enforce something.

So the order is explicit: build the hierarchies, run the backfill, verify, then set this. Server-owned.

v1.24. Switches the shelf-measurement module on for this tenant (roadmap §12): photos carry a subject, locations carry expected, shelf photos are measured and visits roll up into Task.measurement. One build serves every tenant; clients show the module's screens when this is true and nothing of it otherwise. Server-owned. Absent means false.

Keyed by stringified category_id.

Last observed HTTP status from the health probe.

The oldest build that may be used: Android's versionCode. A build below it shows nothing but "update to continue" and offers the update, so it starts nothing new: no browsing, no capture.

It is not a kill switch. What the build had already queued — a photo taken, a document written offline — still drains, because a photo stranded on a phone is worse than one more write in an old shape. A release that must refuse an old shape refuses it in the rules or the API; this field is what tells the person why.

Raise it only once the build that satisfies it has reached every install (on Play: rolled out on the track people are on, not merely uploaded) — a phone told to update to a build its store does not offer yet can do nothing. User.version_code says who would be stopped.

The original capture's trace, so the retry stays on it.

The failed job, when one was minted before failure.

Deployed service version — the git SHA baked at build. HTTP mapping: ok and degraded (some preload models missing) are 200; unavailable is 503.

Model identifiers currently resident, for warm-start diagnosis.

The tenant in scope, or the reserved platform when there is none (health, startup, requests rejected before identity is resolved).

Present whenever the work descends from a capture.

Human-readable summary. Never parsed — put anything structured in payload.

Set on analysis.* records, so model quality is trendable by version.

Module-specific detail; the only part of the record that is not shared vocabulary. vision should break its timings down by stage here — download, detect, classify, write — so that "analysis is slow" resolves to a stage rather than a shrug.

Fixed HTTP mapping — 400 invalid_argument; 401 unauthenticated; 403 tenant_mismatch when the tenant differs, else permission_denied; 404 not_found; 409 conflict; 503 model_unavailable (health) or unavailable (dependency); 500 internal. Body-validation failures are rendered into this shape with the field errors in details, never as a framework 422.

Correlates with server logs.