Dynamic meter creation

Ingest events for meters, meter values and meter properties that don’t exist yet; Solvimon creates them on the fly as part of processing the event.

Why this matters

Normally an event is rejected when it references a meter, meter value or meter property that hasn’t been configured yet. Dynamic meter creation removes that requirement: you can let events drive the meter configuration instead of pre-creating every meter, value and property up front. This is useful when your usage model is still evolving.

Enabling it per request

The behaviour is controlled by the meter_validation query parameter on POST /v1/ingest/meter-data:

What gets created

When a DYNAMIC event is ingested, Solvimon ensures every referenced resource exists before processing the event:

• Meter: created when the meter_reference is unknown.
• Meter value: each referenced value that doesn’t exist is created.
• Meter property: each referenced property that doesn’t exist is created.
• ENUM value: if a referenced property already exists and is of type ENUM, but the submitted value isn’t in its list of allowed values, the value is added to the list.

If the meter already exists, it is extended with any values, properties or ENUM values that are still missing.

The created resources use these defaults:

Values and properties are linked to the meter as not required by default, so a dynamically-created meter never blocks subsequent events.

Controlling type and required

By default a created meter property is a STRING and every association is optional. You can override this per value or property with an optional dynamic_validation_settings object on the meter_values[] and meter_properties[] entries of the event. These settings are only used when the resource is created on the fly and are ignored when it already exists.

Example

The following event creates the meter_subscriptions meter (if it doesn’t exist), a required ENUM property plan seeded with the value pro, and a NUMBER value seats, all in a single ingest call:

1
curl -X POST "https://test.api.solvimon.com/v1/ingest/meter-data?meter_validation=DYNAMIC" \
2
     -H "X-API-KEY: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "reference": "00124578951",
6
  "customer_reference": "9923725805",
7
  "meter_reference": "meter_subscriptions",
8
  "timestamp": "2024-07-01T10:50:00+02:00",
9
  "meter_properties": [
10
    {
11
      "reference": "plan",
12
      "value": "pro",
13
      "dynamic_validation_settings": {
14
        "type": "ENUM",
15
        "required": true
16
      }
17
    }
18
  ],
19
  "meter_values": [
20
    {
21
      "reference": "seats",
22
      "number": "25"
23
    }
24
  ]
25
}'

1
{
2
  "object_type": "meter_data",
3
  "id": "md_9876543210",
4
  "reference": "00124578951",
5
  "type": "INGEST",
6
  "customer_reference": "9923725805",
7
  "meter_reference": "meter_subscriptions",
8
  "timestamp": "2024-07-01T10:50:00+02:00",
9
  "meter_properties": [
10
    {
11
      "reference": "plan",
12
      "value": "pro"
13
    }
14
  ],
15
  "meter_values": [
16
    {
17
      "reference": "seats",
18
      "number": "25"
19
    }
20
  ]
21
}

This ensures the meter, the plan property (ENUM, required, with pro as an allowed value) and the seats value (NUMBER) all exist before the event is processed.

Idempotency and concurrency

Resource creation is idempotent and safe to retry. If two events for the same new meter (or value/property) arrive at the same time, only one resource is created: the other request detects the duplicate reference and reuses the resource that won the race, so no event fails because of a creation conflict.

Notes and limitations

• meter_validation=DYNAMIC only affects ingestion. It does not change how meters behave once created; a dynamically-created meter is an ordinary meter that you can manage in Desk or via POST /v1/meters.
• For an existing meter, the creation step only runs when the event actually references something missing; otherwise ingestion follows the normal path.
• The submitted value still has to be valid for the (existing or newly-created) value or property type. For example, a NUMBER value must be a valid number.

See also: Meters, Meter values, Meter properties and the Event ingestion API.