🤝

Premium Add-on

Please contact our commercial team if you are interested in using this functionality.

The predicted cost of an ingested event can be obtained through two primary methods: Solvimon Desk and developers by incorporating a designated query parameter in the API Request during event ingestion.

API Request

We will show the cost prediction in both Solvimon Desk and within the API Request for the following meter-data ingest event:

{
  "meter_reference": "card_issuing",
  "customer_reference": "Customer_GUID",
  "reference": "event-ingestion-17-04-2023",
    "meter_values": [
    {
      "reference": "card_count",
      "number": "1"
    }
  ],
  "meter_properties": [
    {
      "reference": "card_type",
      "value": "Visa"
    },
    {
      "reference": "card_use_frequency",
      "value": "Single"
    }
  ]
}

The cost prediction will calculate the contribution of an ingested event for the provided customer (customer_id/customer_reference) and meter(meter_id/meter_reference). The predicted cost of the event is an estimation of the eventual price.

Due to our multi-distributed platform events can be processed in parallel to support high throughput. As a result we can not guarantee 100% accuracy. An unlikely example is two events reaching our platform simultaneously. Both of which would result in the next tier being reached.

Event processing details

In the Desk Events page, users have the ability to access detailed event information by selecting a specific event. When accessing, users are directed to the event processing details page, where a summary of the ingested event is shown, alongside the cost estimation data.

API Response

The API reference outlines the specific query parameters available for each resource. To include predicted cost data in the response, developers should use the cost_prediction query parameter, setting it to a boolean value true when submitting a meter-data event ingestion request.

When making a POST request to the endpoint /v1/ingest/meter-data?cost_prediction=true with the provided JSON payload, the response will contain an additional element called cost_prediction, structured as follows:

{
  ...
  "cost_prediction": {
    "response": "OK",
    "details": [
      {
        "customer_id": "cust_ywDeeN0teYVm9GAGeN1j",
        "amount_excluding_tax": {
          "quantity": "0.07",
          "currency": "EUR"
        },
        "amount_including_tax": {
          "quantity": "0.08",
          "currency": "EUR"
        },
        "tax_summary": {
          "base_amount": {
            "quantity": "0.07",
            "currency": "EUR"
          },
          "tax_amount": {
            "quantity": "0.01",
            "currency": "EUR"
          },
          "total_amount": {
            "quantity": "0.08",
            "currency": "EUR"
          },
          "country_code": "NL"
        },
        "periods": [
          {
					...
          }
        ]
      }
    ]
  }
}

This JSON structure includes the following prediction details:

1. response: indicating either OK or FAILED.
2. details [OPTIONAL]: an array containing cost predictions per customer, including the amount excluding and including tax, a tax summary, and the applicable periods. For more information on the periods structure, refer to the API reference.

Currently, the cost predictions apply only to flat pricing and do not account for tiering or other configurations, such as included volume.

The details object will be absent in the following scenarios:

1. The event resulted in no match for the combination customer, meter and subscription. Example given, when the event was ingested with a timestamp that was either before or after the subscription was active
2. The pricing configuration for which the event was matched against, has been configured with pricing_type: NONE also known as Not billed.

The cost prediction will result in a 0 (zero) quantity when:

1. The pricing configuration has included volume and the event count is still within this included volume

❗️

Cost prediction response

The cost_prediction_groups response field is deprecated, and will be replaced by the new cost_prediction structure.

Failed response

Although the cost prediction is unlikely to fail, it is possible.

If the response status is marked as FAILED, it indicates that either we were unable to calculate the cost for the event, or the calculation exceeded the allowed time limit of 5 seconds. This time constraint is imposed to prioritize the ingestion of the event over the completion of the cost prediction.

There are two options to recover from this scenario:

1. Resubmit the event with the same reference. Due to Idempotency, the event details will not be processed again, so the invoice will not be affected. However, the cost prediction may differ slightly (e.g., if the initial estimate was 10 EUR, the new submission might result in 9 EUR due to tiered pricing).
2. Delete the initial event ingestion and then resubmit the event.

The second option requires a manual intervention to reprocess the invoice, before re-submitting the event