Copy page

Common workflows

Create an offer

Use this workflow to create an Offer that can be sent to a customer for review, consent, or digital signature.

An Offer uses much of the same structure as Contract creation, but includes additional properties for managing the signing process, signers, language, cool-off periods, and signing deadlines.

Endpoint

Code
POST /v1/cm/offers

When to use

Use this workflow when a customer should receive an offer before the contract process is completed.

Typical use cases include:

• creating an offer that the customer must sign digitally
• creating an offer that requires customer consent
• creating an offer with one or more signers
• creating an offer with a signing deadline
• creating an offer where signing is only allowed after a cool-off period
• creating an offer based on one or more Accounting Points and Products

Request structure

The request uses the same main structure as Contract creation, with additional offer-specific fields.

The request typically contains:

Field	Description
RequestId	Unique request id. Use a new GUID for each request.
StartDate	Start date for the offer or resulting contract flow.
Customer	Customer information.
Account	Account information. The Account is the invoice-related grouping for the customer.
AccountingPoint or AccountingPoints	One or more Accounting Points included in the offer.
Products	Products included in the offer.
Options	Optional processing options.
SignRequestType	Defines the signing or consent workflow.
Signers	List of persons that should sign or consent to the offer.
CoolOffBeforeSign	Indicates whether signing should be delayed until a specified date.
FirstAvailableSignDate	Earliest date and time when signing is allowed. Only used when CoolOffBeforeSign is true.
LastAvailableSignDate	Required signing deadline.
DueDaySettingsType	Defines how invoice due date should be calculated.
InvoicePaymentTerms	Number of days or fixed day value depending on DueDaySettingsType.

Example request

Code
{
  "RequestId": "7f4b0b8e-6d8b-4a72-9f2c-2f2d1fd8a001",
  "StartDate": "2026-06-01T22:00:00Z",
  "Customer": {
    "Identification": "31074355544",
    "GivenName": "Kari",
    "FamilyName": "Nordmann",
    "PreferredLanguage": "no",
    "Identifiers": [
      {
        "Source": "CRM",
        "Identification": "100157",
        "Description": "Customer number in CRM"
      }
    ]
  },
  "Account": {
    "Name": "Main account",
    "Addresses": [
      {
        "Type": "invoiceadr",
        "StreetName": "Example Street",
        "BuildingNumber": "1",
        "PostCode": "0123",
        "CityName": "Oslo",
        "CountryCode": "NO"
      }
    ],
    "Communication": [
      {
        "Channel": "Email",
        "Value": "customer@example.com"
      },
      {
        "Channel": "Mobile",
        "Value": "+4799988777"
      }
    ]
  },
  "AccountingPoint": {
    "Identification": "707057500012345678"
  },
  "Products": [
    {
      "ProductId": "6d1224116b6f42979815836fb343bb60",
      "ProductName": "Fastpris 1 år",
      "PrimaryProduct": true,
      "StartDate": "2026-06-01T22:00:00Z",
      "InteractivePrices": [
        {
          "Name": "i:Paaslag",
          "Value": "0.73"
        }
      ]
    }
  ],
  "Options": {
    "SkipRequestStartOfSupplyFromMarket": false,
    "SkipRequestAccountingPointCharacteristicsFromMarket": false,
    "SkipRequestAccountingPointMeterValuesFromMarket": false,
    "SkipCustomerConfirmation": true,
    "SkipCustomerCreditCheck": false
  },
  "SignRequestType": "SignWithAuth",
  "Signers": [
    {
      "Identification": "31074355544",
      "Name": "Kari Nordmann",
      "Email": "customer@example.com",
      "Mobile": "+4799988777"
    }
  ],
  "CoolOffBeforeSign": false,
  "FirstAvailableSignDate": "2026-05-30T22:00:00Z",
  "LastAvailableSignDate": "2026-06-30T22:00:00Z",
  "DueDaySettingsType": 0,
  "InvoicePaymentTerms": 14
}

Customer and Account

The Customer and Account objects follow the same principles as Contract creation.

The offer can be created for a new or existing customer. If the customer already exists, identifiers such as Customer.Guid, Customer.Identification, or Customer.Identifiers can be used to identify the customer.

The Account contains invoice-related information such as invoice address and communication details.

Customer fields

Field	Description
Guid	Optional UtilityCloud GUID for an existing customer.
Identification	National identity number or organization number.
Name	Company name. Used for business customers.
GivenName	Given name. Used for private customers.
FamilyName	Family name. Used for private customers.
PreferredLanguage	Customer language. Used for offer and signing communication. Supported values are typically en, no, fi, sv, and et.
Identifiers	External identifiers used for synchronization with other systems.

Account fields

Field	Description
Guid	Optional UtilityCloud GUID for an existing account.
Name	Optional account name.
Addresses	Invoice and/or postal address.
Communication	Email, mobile, or phone information.
Identifiers	External identifiers used for synchronization with other systems.

Accounting Point

The AccountingPoint object identifies the Accounting Point included in the offer.

Code
{
  "AccountingPoint": {
    "Identification": "707057500012345678"
  }
}

To create offers for multiple Accounting Points, use AccountingPoints instead of AccountingPoint.

Code
{
  "AccountingPoints": [
    {
      "Identification": "707057500012345678"
    },
    {
      "Identification": "707057500087654321"
    }
  ]
}

Products

The Products array defines the products included in the offer.

Code
{
  "Products": [
    {
      "ProductId": "6d1224116b6f42979815836fb343bb60",
      "ProductName": "Fastpris 1 år",
      "PrimaryProduct": true,
      "StartDate": "2026-06-01T22:00:00Z",
      "InteractivePrices": [
        {
          "Name": "i:Paaslag",
          "Value": "0.73"
        }
      ]
    }
  ]
}

Product fields

Field	Description
ProductId	Identifier of an existing product in UtilityCloud.
ProductName	Optional product name.
PrimaryProduct	Indicates whether the product is the primary product.
StartDate	Date from which the product should apply.
EndDate	Optional end date for the product.
InteractivePrices	Product-specific price values. Required when the product has interactive fields.

Products used in an Offer must already exist in UtilityCloud.

Some products have interactive fields. When a product has interactive fields, the InteractivePrices array must include name-value pairs for the required fields. Values should be specified in the primary currency unit, using period (.) as decimal separator when decimal values are used.

Options

The Options object controls additional processing.

Code
{
  "Options": {
    "SkipRequestStartOfSupplyFromMarket": false,
    "SkipRequestAccountingPointCharacteristicsFromMarket": false,
    "SkipRequestAccountingPointMeterValuesFromMarket": false,
    "SkipCustomerConfirmation": true,
    "SkipCustomerCreditCheck": false
  }
}

Field	Description
SkipRequestStartOfSupplyFromMarket	Set to true if no start of supply message should be sent to the market hub.
SkipRequestAccountingPointCharacteristicsFromMarket	Set to true if Accounting Point characteristics should not be requested from the market hub.
SkipRequestAccountingPointMeterValuesFromMarket	Set to true if meter values should not be requested from the market hub.
SkipCustomerConfirmation	Controls whether customer confirmation is skipped.
SkipCustomerCreditCheck	Controls whether customer credit check is skipped.

Signing fields

Offer requests include additional fields for signing and consent handling.

Field	Description
SignRequestType	Defines the signing or consent workflow.
Signers	List of persons that should sign or consent to the offer.
CoolOffBeforeSign	If true, signing is not allowed before FirstAvailableSignDate.
FirstAvailableSignDate	Earliest date and time when signing is allowed. Only used when CoolOffBeforeSign is true.
LastAvailableSignDate	Required signing deadline.

Sign request types

The following sign request types are supported:

SignRequestType	Description
ConsentNoAuth	Consent flow where authentication is not required to view the documents. The customer can view the documents without authentication and consent after viewing.
ConsentWithAuth	Consent flow where authentication is required to view the documents. The customer must authenticate before viewing the documents and can consent after viewing.
SignNoAuth	Signing flow where authentication is not required to view the documents. The customer can view the documents without authentication, but must authenticate to sign.
SignWithAuth	Signing flow where authentication is required to view the documents and sign.

Signers

The Signers array defines who should sign or consent to the offer.

Code
{
  "Signers": [
    {
      "Identification": "31074355544",
      "Name": "Kari Nordmann",
      "Email": "customer@example.com",
      "Mobile": "+4799988777"
    }
  ]
}

Signer fields

Field	Description
Identification	Personal identification number for the signer.
Name	Full name of the signer.
Email	Email address used to send signing information.
Mobile	Mobile number with country calling code used to send signing information by SMS.

Invoice payment terms

The offer may include invoice payment terms.

Field	Description
DueDaySettingsType	Use 0 for number of days after invoicing, or 1 for a fixed day number of the month.
InvoicePaymentTerms	Number of days or fixed day value, depending on DueDaySettingsType.

Response

A valid request returns:

Code
202 Accepted

The operation is accepted for processing.

The resulting offer can then be used in the configured signing, consent, or customer acceptance flow. Depending on Service Type and tenant configuration, the offer flow may involve signing, consent handling, contract creation or update, market communication, settlement setup, billing setup, and events.

Notes

Use a new RequestId for each request. The request id is used for tracing and duplicate request handling.

Use PreferredLanguage on the Customer object to control the customer's language in the offer and signing flow. Supported values are typically en, no, fi, sv, and et.

Use LastAvailableSignDate to define the signing deadline.

Use CoolOffBeforeSign together with FirstAvailableSignDate when signing should not be available immediately.

A Contract can contain one primary product and optional add-on products. Offers follow the same product structure.

Related endpoints

Code
POST /v1/cm/offers
POST /v1/cm/contracts
POST /v1/pm/products
GET /v1/cm/offer/{guid}