Data model overview

This guide provides API-facing details for developers building integrations. For a user-friendly introduction, see How your data works in the Knowledge Base.

Entity relationships

Nectar organizes utility data in a hierarchical structure:

Entity definitions

Entity	API resource	Description
Company	`/company`	Top-level entity containing sites and connections
Site	`/company/{id}/site`	Physical address with meters
Connection	`/company/{id}/connection`	Configured link to a utility provider
Account	`/company/{id}/account`	Billing relationship with a utility; discovered via connections
Meter	`/company/{id}/meter`	Measurement point for a single commodity at a site
Document	`/company/{id}/document`	Processed utility statement
UsageData	`/company/{id}/usage`	Time-series consumption record
LineItem	Nested in document	Individual charge or credit on a document

Data processing behavior

When a document enters Nectar, it moves through an external lifecycle: Key behaviors:

Core bill fields, usage data, and line items are extracted from source documents.
Meter/account/site associations are applied to organize data in the API model.
Validation checks run before data is published to improve quality and consistency.
Electricity demand values are included when present in source documents.

Key data fields

Document

Field	Type	Description
`id`	UUID	Unique identifier
`billDate`	Date	End date of billing period
`startDate`	Date	Start date of billing period
`totalCharges`	Decimal	Total amount due
`currentCharges`	Decimal	New charges this period
`chargesUnits`	String	Currency code (USD, EUR, etc.)
`revisedDocumentId`	UUID \| null	When every usage row on this document is revised to the same document, the ID of that replacing document; otherwise null
`supersededDocumentIds`	UUID[]	IDs of documents fully superseded by this one (every usage row on each listed document points here)

UsageData

Field	Type	Description
`id`	UUID	Unique identifier
`revisedDocumentId`	UUID \| null	When this usage record is superseded by a corrected document, the ID of the replacing document
`startDate`	Date	Start of consumption period
`endDate`	Date	End of consumption period
`rawUsage`	Decimal	Usage as reported on bill
`rawUsageUnits`	String	Original unit of measure
`standardUsage`	Decimal	Normalized usage value
`netMeteringType`	Enum	IMPORT, EXPORT, or GENERATION

Document-level revision fields stay compatible for full-document revisions. Usage and emissions exclusions are per usage row; sibling usage without a revision link still contributes. For site cost, superseded rows preserve the earlier document’s historical meter and site allocation.

Meter

Field	Type	Description
`id`	UUID	Unique identifier
`datasourceType`	Enum	Commodity: ELECTRICITY, GAS, WATER, SEWER, etc.
`waterType`	Enum	Water subtype when `datasourceType` is WATER (potable, well, municipal)
`isTracked`	Boolean	Whether included in active analytics
`isDuplicated`	Boolean	Whether marked as duplicate
`tags`	Array	Meter tags assigned to this meter

Calendarization algorithm

Nectar converts billing period data to calendar months using daily proration:

# Simplified algorithm
daily_usage = total_usage / (end_date - start_date + 1)

for month in overlapping_months:
    overlap_start = max(bill_start, month_start)
    overlap_end = min(bill_end, month_end)
    overlap_days = (overlap_end - overlap_start) + 1
    month_usage = daily_usage * overlap_days

Key details:

Inclusive date counting: Both start and end dates are included (closed interval)
Computed at query time: Raw data preserved; calendarization applied dynamically
Net metering exports: Export meters multiply by -1 during aggregation

Cost attribution algorithm

For multi-meter bills, Nectar first assigns line items linked only to one site. It then allocates the remaining net current charges:

net_charges = total_charges - open_balance
remainder = net_charges - directly_assigned_charges
utility_type_share = remainder / utility_types_with_usage
meter_share = utility_type_share * meter_usage / utility_type_usage

Key details:

Uses net current charges so carried balances are not counted again
Falls back to an equal split only when no eligible row has positive usage
Retains superseded rows for historical site cost allocation
Normalizes cross-bill portfolio cost analytics to USD; bill audit views retain native currency

Annotations and computed fields

Several fields are computed at query time rather than stored:

Annotation	Description	Used for
`isArchived`	`dataCollectionStopDate` is set and in past	Filtering inactive sites
`isVisibleByCurrentUser`	User has site permission	Permission filtering
`dailyUsage`	`standardUsage / span_days`	Calendarization
`calendarizedUsage`	`dailyUsage * overlap_days`	Monthly aggregation

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

Entity relationships

Entity definitions

Data processing behavior

Key data fields

Document

UsageData

Meter

Calendarization algorithm

Cost attribution algorithm

Annotations and computed fields

Next steps

Document processing details

Meter organization

​Entity relationships

​Entity definitions

​Data processing behavior

​Key data fields

​Document

​UsageData

​Meter

​Calendarization algorithm

​Cost attribution algorithm

​Annotations and computed fields

​Next steps

Document processing details

Meter organization

Entity relationships

Entity definitions

Data processing behavior

Key data fields

Document

UsageData

Meter

Calendarization algorithm

Cost attribution algorithm

Annotations and computed fields

Next steps