Documentation

Core concepts

UtilityCloud APIs are centered around a set of core business resources. Understanding these resources and how they relate to each other is important before implementing an integration.

Core Resource	Description
Customer	A Customer represents either a private person or a business customer. A private customer is typically identified by a national identity number, while a business customer is typically identified by an organization number. A Customer can have one or more Invoice Groups, Contracts, Metering Points, Contacts, and Identifiers.
Invoice Group	An Invoice Group represents the invoice-related grouping for one or more Contracts. It contains invoice address, communication details, invoice grouping rules, and references to the Customer it belongs to. In current API paths and payloads, this concept is referred to as `Account` or `Invoice Collection`.
Metering Point	A Metering Point represents the point where consumption, production, EV charging, or another measurable service is registered. For electricity, Metering Points may be synchronized with a market hub such as Elhub or a national datahub. For other Service Types, such as district heating, water, broadband, EV charging agreement, or revenue share, the Metering Point may be managed directly in UtilityCloud. In current API paths and payloads, this concept may be referred to as `Accounting Point`.
Contract	A Contract connects a Customer, an Invoice Group, one or more Products, and a Metering Point. The Contract lifecycle is represented through statuses such as pending, active, ended, terminated, halted, reverted, and related transitional statuses. Contract changes may trigger market communication, settlement changes, billing changes, events, or signing and consent workflows depending on the Service Type and configuration.
Offer	An Offer represents a proposed agreement that can be sent to a Customer before a Contract is created or activated. Offers use much of the same structure as Contract creation, but include additional information related to the offer and signing process. This may include signers, preferred language, signing request type, cool-off period, first available signing date, last available signing date, and invoice and payment terms. In the existing API, Offers are handled through the CM domain and are typically created using `POST /v1/cm/offers`. Use Offers when the Customer must review, accept, consent to, or sign an agreement before the final Contract flow is completed.
Product	A Product defines what is sold or delivered under a Contract or Offer, how it is priced, and how it should be used in Contract and settlement processes. A Contract can contain a primary Product and optional add-on Products. Some Products may require interactive price values or other product-specific input when a Contract or Offer is created. Billing-specific items such as fees, charges, credits, down payments, reminder fees, interest, and administration fees may be represented as product-related elements in billing processes.
Price List	A Price List represents pricing configuration used by Products and settlement calculations. In the existing API, price list information is closely related to Product setup, product visibility, price expressions, interactive prices, and price information returned for a Customer and Metering Point. Products and Price Lists define how amounts are calculated for settlement and invoicing. Some Products have interactive fields that must be supplied when creating a Contract or Offer. These values are provided through `InteractivePrices` or price-related fields in the product payload. In the existing API, product and price-related information may be retrieved through PM and SE endpoints, for example `GET /v1/pm/products` and `GET /se/v2/GetPriceInformation`. Use Price List documentation to explain how Products, price elements, interactive prices, add-on Products, fees, charges, and calculated price information relate to each other.
Invoice	An Invoice represents billed amounts for one or more Contracts within an Invoice Group. Invoice data may include invoice number, invoice date, due date, amount, remaining amount, status, distribution information, Invoice Lines, and PDF access information.
Invoice Line	An Invoice Line represents a detailed line item on, or related to, an Invoice. Invoice Lines are used to describe the individual amounts that make up an Invoice, such as energy consumption, fixed fees, add-on Products, corrections, debt collection fees, or other billable items. Invoice details can be retrieved for an Invoice, and some endpoints also support adding or moving Invoice Lines in specific billing or debt collection scenarios. Relevant existing API examples include `GET /be/v3/invoice/details`, `POST /be/v3/lines/imported`, and `POST /be/v3/invoice/debtcollection/invoicelines`.
Service Type	A Service Type defines the market, utility domain, and configuration context for a resource or process in UtilityCloud. Service Type is used to determine how Contracts, Metering Points, Products, Offers, settlement, billing, and market communication should behave for a specific business area. Examples of Service Type usage include identifying whether a Contract is for electricity, district heating, EV charging, revenue share, or another service area, determining whether market communication should be performed, controlling which Metering Point fields are required, controlling which Products are available, and influencing validation, settlement, billing, and user flows. In the existing API, Service Type is commonly represented through fields such as `ServiceType`, `ServiceTypeKey`, or `Type`, depending on the endpoint and payload.
Meter Values	Meter Values represent measured, estimated, or calculated time series values for a Metering Point over time. In current API paths and payloads, the related resource may be referred to as `Accounting Point`. The exposed API endpoints for ingesting Meter Values are primarily used for time series values that must be settled in UtilityCloud, but that are not received from a national energy market hub such as Elhub in Norway or Datahub in Finland. These values are typically provided directly by an external meter data system, partner system, or integration. Meter Values may include consumption or production.

Getting Started Authentication

Core concepts

UtilityCloud APIs are centered around a set of core business resources. Understanding these resources and how they relate to each other is important before implementing an integration.

Core Resource

Description

Customer

A Customer represents either a private person or a business customer. A private customer is typically identified by a national identity number, while a business customer is typically identified by an organization number. A Customer can have one or more Invoice Groups, Contracts, Metering Points, Contacts, and Identifiers.

Invoice Group

An Invoice Group represents the invoice-related grouping for one or more Contracts. It contains invoice address, communication details, invoice grouping rules, and references to the Customer it belongs to. In current API paths and payloads, this concept is referred to as Account or Invoice Collection.

Metering Point

A Metering Point represents the point where consumption, production, EV charging, or another measurable service is registered. For electricity, Metering Points may be synchronized with a market hub such as Elhub or a national datahub. For other Service Types, such as district heating, water, broadband, EV charging agreement, or revenue share, the Metering Point may be managed directly in UtilityCloud. In current API paths and payloads, this concept may be referred to as Accounting Point.

Contract

A Contract connects a Customer, an Invoice Group, one or more Products, and a Metering Point. The Contract lifecycle is represented through statuses such as pending, active, ended, terminated, halted, reverted, and related transitional statuses. Contract changes may trigger market communication, settlement changes, billing changes, events, or signing and consent workflows depending on the Service Type and configuration.

Offer

An Offer represents a proposed agreement that can be sent to a Customer before a Contract is created or activated. Offers use much of the same structure as Contract creation, but include additional information related to the offer and signing process. This may include signers, preferred language, signing request type, cool-off period, first available signing date, last available signing date, and invoice and payment terms. In the existing API, Offers are handled through the CM domain and are typically created using POST /v1/cm/offers. Use Offers when the Customer must review, accept, consent to, or sign an agreement before the final Contract flow is completed.

Product

A Product defines what is sold or delivered under a Contract or Offer, how it is priced, and how it should be used in Contract and settlement processes. A Contract can contain a primary Product and optional add-on Products. Some Products may require interactive price values or other product-specific input when a Contract or Offer is created. Billing-specific items such as fees, charges, credits, down payments, reminder fees, interest, and administration fees may be represented as product-related elements in billing processes.

Price List

A Price List represents pricing configuration used by Products and settlement calculations. In the existing API, price list information is closely related to Product setup, product visibility, price expressions, interactive prices, and price information returned for a Customer and Metering Point. Products and Price Lists define how amounts are calculated for settlement and invoicing. Some Products have interactive fields that must be supplied when creating a Contract or Offer. These values are provided through InteractivePrices or price-related fields in the product payload. In the existing API, product and price-related information may be retrieved through PM and SE endpoints, for example GET /v1/pm/products and GET /se/v2/GetPriceInformation. Use Price List documentation to explain how Products, price elements, interactive prices, add-on Products, fees, charges, and calculated price information relate to each other.

Invoice

An Invoice represents billed amounts for one or more Contracts within an Invoice Group. Invoice data may include invoice number, invoice date, due date, amount, remaining amount, status, distribution information, Invoice Lines, and PDF access information.

Invoice Line

An Invoice Line represents a detailed line item on, or related to, an Invoice. Invoice Lines are used to describe the individual amounts that make up an Invoice, such as energy consumption, fixed fees, add-on Products, corrections, debt collection fees, or other billable items. Invoice details can be retrieved for an Invoice, and some endpoints also support adding or moving Invoice Lines in specific billing or debt collection scenarios. Relevant existing API examples include GET /be/v3/invoice/details, POST /be/v3/lines/imported, and POST /be/v3/invoice/debtcollection/invoicelines.

Service Type

A Service Type defines the market, utility domain, and configuration context for a resource or process in UtilityCloud. Service Type is used to determine how Contracts, Metering Points, Products, Offers, settlement, billing, and market communication should behave for a specific business area. Examples of Service Type usage include identifying whether a Contract is for electricity, district heating, EV charging, revenue share, or another service area, determining whether market communication should be performed, controlling which Metering Point fields are required, controlling which Products are available, and influencing validation, settlement, billing, and user flows. In the existing API, Service Type is commonly represented through fields such as ServiceType, ServiceTypeKey, or Type, depending on the endpoint and payload.

Meter Values

Meter Values represent measured, estimated, or calculated time series values for a Metering Point over time. In current API paths and payloads, the related resource may be referred to as Accounting Point. The exposed API endpoints for ingesting Meter Values are primarily used for time series values that must be settled in UtilityCloud, but that are not received from a national energy market hub such as Elhub in Norway or Datahub in Finland. These values are typically provided directly by an external meter data system, partner system, or integration. Meter Values may include consumption or production.