Send your usage data

Sending usage data is the first thing to do to unlock Hyperline’s potential when you have a usage based model, but there are a few tips to make the most out of our system.

First, we’re not an analytics API, sending us page views, user logins or other non-critical events doesn’t really make sense as you probably won’t use them for your pricing and packaging anyways. If you need a great product analytics solution, we recommend you check out our friends at June.so or at Mixpanel.

This being said, you shouldn’t restrain from sending data that you’re not using yet. Hyperline is designed for you to iterate on your pricing & packaging and will allow you to run experiments and simulations from the data we have ingested.

The best way to think about events to send us is to ask yourself if you’ll use the data either

• To price your product (ex: price per user or per API call)
• Limit usage (ex: free up to 5GB of storage)
• Orchestrate pricing-related workflows (ex: when a customer reaches X, show a paywall).

In doubt, just send it, once it’s in the system, you’ll be able to play with it and may discover some new opportunities.

​

Ingestion basics

Events payloads always follow the same (minimalist) structure and can be sent to the POST /events endpoint. The record object can contain any additional properties of type string, number, boolean, and array of these types but arrays of objects will be rejected.

Events are processed instantly, you can go to your events page and refresh it to see it.

You can send as many as 50 events per second before being rate-limited. We’ll increase these limits as our infrastructure grows, please contact us if you need a custom limit.

Here’s an example payload

{
  "customer_id": "cus_fh4585Jjrekkk",
  "timestamp": "2022-01-05 21:56:52",
  "event_type": "new_transaction",
  "record": {
    "id": 485,
    "amount": 2500
  }
}

​

Security and privacy

Even though we’re making some basic security check, we can’t filter every personal or confidential data off our systems automatically.

Most of the time you don’t need personal information in Hyperline so we recommend you remove or obfuscate (for instance, John becomes J***).

• People names
• People’s personal email addresses
• Phone numbers
• Payment information like card numbers or IBANs
• Physical addresses
• Anything that could help identify someone’s identity or localization

In our systems, we’re responsible for keeping your data safe, but you’re in charge of the content itself, so be careful, your customer’s safety is an important matter.

​

Events or entities?

Hyperline is designed to rely fully on events for data ingestion. We can then apply a variety of operators to configure how you want to aggregate data (count, sum), and filters (equals, “is null” check, greater/lower than comparators, etc.).

In the first case, Hyperline will treat your events as entities or models, meaning that one event will represent one item in our database, independently of its timestamp.

For instance, let’s say you want your customer to pay 5€ per user, you’ll send us the following event when a new user is registered.

{
  "customer_id": "<customer_id>", // Hyperline ID or external ID of the existing customer
  "timestamp": "2023-11-12T00:00:00.000Z", // used to aggregate depending on the billing period
  "event_type": "users", // use the name you want
  "record": {
    "id": 258,
    "work_email": "l***.c***@yourcompany.com",
    "created_at": "2023-11-12T00:00:00.000Z",
    "deleted_at": null // we'll use this field later
  }
}

Then you’ll create a dynamic product that counts your users, and apply a volume pricing to it by defining an interval and the related pricing tiers.

We offer you a preview of the evolution of this pricing to make it more visible regarding how it evolves with the increase of items.

​

Update and delete events

Now you may be thinking, what happens if I send an event that shouldn’t be billed? Or if need to make a change to an entity?

Hyperline’s API is an append-only system, meaning that except through our interface, we don’t allow update or delete operations. But don’t worry, we got you covered.

​

Updating an event

Each event is identified by a unique key composed of 2 parameters:

• event_type
• record.id

When Hyperline detects a new event with the exact same 2 keys, it will consider that this new event overrides the previous one and therefore will replace it in the database.

In other words, updating an event is just like creating one, just send the same payload with the updated field and it will be updated.

To find out which event is the latest, we’re using the timestamp value.

Using our users again, here’s an example where we add a “status” property

{
  "customer_id": "<customer_id>",
  "timestamp": "ACTIVE_DATE",
  "event_type": "users",
  "record": {
    "id": 258,
    "status": "premium",
    "work_email": "l***.c***@yourcompany.com",
    "created_at": "2022-01-01 10:00:00",
    "deleted_at": null
  }
}

The event in the database will now have a premium status and the previous version will not exist anymore. If you need to keep both versions, you’ll need to provide a different record.id.

​

Deleting an event

If you sent an event by mistake, you can delete them in the Events tab on the app. But this is not the way to manage standard deletions, for instance when a user is removed from an account.

There are many ways to manage this, the first one is to use the deleted_at key we added early and set it to something different than null. Then update the usage product we created earlier to filter out records where deleted_at is not null like so.

Another option is to use a state or a flag in the model, for instance, an active boolean field in the user entity that you can toggle to off. The principle stays the same, just set a property to the right value and filter out the elements you don’t want.

​

Limitations

In order to process massive numbers of events, Hyperline had to adopt a rigid structure for events. While quite permissive, there are 2 main limitations:

• Record properties can’t be nested (only one level of properties is allowed)
• Records can’t have more than 25 properties