Event ingestion API

The most automated and efficient way of using the Solvimon platform is to have your Engineering team integrate with our easy event ingestion API.

Preparation

Before your Engineering team can start implementing the logic to send data to our Ingest API, a little preparation is still required. You need at least one meter with a meter value including a calculation method. If you haven't configured that yet, please go to our Platform Configuration Guide or directly to the Meters documentation.

API request examples

Ingesting events is done through the POST ingest event endpoint. You can use the Desk portal to create an example JSON of your specific meter. Go to Desk > Events > Select meter > Ingest event and fill the manual event ingestion pane with example data.

A simple usage event might look like this:

{
  "meter_reference": "meter_authorised_transactions",
  "customer_reference": "9923725805",
  "timestamp": "2024-07-01T10:50:00+02:00",
  "reference": "00124578951",
  "meter_properties": [
    {
      "reference": "card_scheme",
      "value": "Mastercard"
    },
    {
      "reference": "card_present",
      "value": "Card Not Present"
    },
    {
      "reference": "card_country",
      "value": "JPN"
    },
    {
      "reference": "location_country",
      "value": "GBR"
    }
  ],
  "meter_values": [
    {
      "reference": "transaction_count",
      "number": "450"
    }
  ]
}

The meter values depend on the settings of your billable meters, and there can be multiple values depending on how many meter values and properties are attached to them. In the example above, the meter only has one value of the type NUMBER.

Read more about Idempotency here

Best practices

Fill Solvimon references with your own system GUID

The reference field is a required field on all resources but can (for example) be filled with your own GUID.
To guarantee uniqueness, the reference of the events should be unique. Based on the reference the Solvimon platform determines idempotency. Compared to other APIs, for the event API the idempotency (duplicate check) is done in an async way. This means that also duplicates will be accepted correctly, but only 'the first' event received with the reference will be processed. Any other event with the same reference will be flagged as DUPLICATE (and will not be processed).

Retry Failed events

There could be a situation where event ingestion fails. For example, because your platform can not reach Solvimon. Or, in case the Solvimon platform returns an error code (like 500). For these kind of situations we always advise to implement a retry policy to retry failed events.

To achieve this, before sending events to Solvimon, we advise to store the event first locally. Only when stored successfully, send the event to Solvimon. In case of an error, you could retry. A best practice is to apply an exponential backoff strategy. In case you you are not able to successfully ingest events to Solvimon, we advise to stop retrying, and contact Solvimon. They can advise when to continue retrying.

By first storing the event, you are sure that you will never loose an event. Furthermore, when an event is accepted, you can store the received resource id (part of the ingest response) as well. This will make 'finding/ mapping the event' in Solvimon easier, in case needed.
In case of an error response, it would be good to log/ store the X-REQUEST-IDheader value from the response. This could help Solvimon to investigate the issue.

Send unique product usage events

Sending individual usage events helps make your usage data more generic and keeps all the billing logic to be configured within the pricing plans. It allows you to iterate on pricing with just a few adjustments and no engineer is needed to update your integration with Solvimon.

Therefore we advise to send your product usage data as granually as you can, so your Product and/or Billing teams can use Solvimon to take care of the rest!

👍

Plan a technical workshop

The onboarding process includes onboarding workshops for stakeholders such as engineering teams to get a better idea of our API and how to integrate in the best and most scalable way.

Get in touch with our support team to plan a workshop.