Events

This guide explains how Mentium ingests usage-based events coming from your application.

Define a Billable metric

Events are designed to target specific Billable metrics created from the dashboard. If you haven't already, we recommend you check it out it first.

You need to define a Billable metric from the UI to send usage measurement events:

1. In the Mentium App, go to the Plans > Billable metrics section

2. Click on the Create button

3. Fill the Billable metric informations.

   • A name

   • A event_type (It will be generated for you but you can override it if needed)

   • A description (optional)

4. Specify the property to aggregate

5. Choose the Aggregation type to define how ingested events must be calculated at the end of the billable period

A Billable metric must be representative of a paying feature of your company. Based on your customers’ actions within your application, implemented events are automatically triggered, aggregated and calculated by Mentium.

Send usage events

To send usage events to Mentium, you need to use the Mentium API. A measurement event is JSON with the following fields:

{
  "transaction_id": "__TRANSACTION_ID__", // (Required) Indempotency key
  "customer_id": "__CUSTOMER_ID__", // (Required) Unique identifier of your customer performing the action
  "event_type": "__EVENT_TYPE__", // (Required) Your Billable metric's Code
  "timestamp": "2017-01-15T01:30:15.01Z", // (Optional) the Timestamp is encoded as a string in the RFC 3339 format
  "properties": {
    "foo": 12.45, // (Optional) Custom variables defined as properties
  }
}

1. The transaction_id

The transaction_id ensure the uniqueness of the events received. It is mandatory to define on your own a unique transaction_id for each event you send to Mentium.

• If a transaction_id is new to Mentium, the event is ingested;

• If a transaction_id has already been received by Mentium, it’s ignored.

2. The customer_id

The customer_id is the ID given by Mentium when you create a new customer with the API or on the dashboard.

4. The event_type

The event event_type represents the unique event_type of the Billable metric you want to start ingest measurements on.

5. The timestamp

The timestamp is the date when the billing event occurs in your application. This event must be a string in the RFC 3339 format. For example, "2017-01-15T01:30:15.01Z".

This timestamp is not mandatory to send the event. If you do not specify a timestamp on your own, Mentium automatically defines the reception date of the event as the event timestamp.

6. The event properties

Event properties are useful to send more context in usage events.and when you need to aggregate a Billable metrics for SUM, MAX and UNIQUE COUNT. Event properties can be strings, integers or floats

Sending an event

Sending a usage event is very easy, you just need to make a POST HTTP request with your favorite client with specifying your API Key in the header. Here is an example with curl

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "event_type":"payment",
    "customer_id":"92cee7bb-b6cb-411b-bfac-6529a01d7eed",
    "transaction_id":"11c4359-a129-4720-83ff-acbb2039916d",
    "timestamp": "2017-01-15T01:30:15.01Z",
    "properties": {
        "amount": 12.50,
        "user_id": "a25b1ab3-6f53-4555-9f98-bea8f4bdc2d9"
     }}' \
  http://api.sandbox.mentium.io/v1/events