Events

Events are the building blocks of usage tracking. They represent individual actions or occurrences that you want to monitor and analyze. Each event can have associated properties that provide additional context about the action. Some examples of events include:

• Song played
• Message sent
• File upload
• API call

You must record usage events in Billingrails to make sure you bill your customers the correct amounts each billing period. Events can be sent using the Events Ingestion API. Here is an example of an event:

{
  "event_name": "Song played",
  "properties": {
    "song_id": "12345",
    "artist": "The Beatles",
    "album": "Abbey Road",
    "duration": 240,
    "billingrails_account_id": "acct_67890"
  },
  "idempotency_key": "unique_event_id_12345",
  "timestamp": "2023-10-01T12:00:00Z"
}

Idempotency

By using an idempotency_key, you can ensure that the same event is not recorded multiple times. This is particularly useful in scenarios where network issues might cause retries. The idempotency_key should be a unique identifier for each event, such as a UUID or a combination of event attributes. If you don't provide an idempotency_key, the server will generate one for you, but it's recommended to supply your own to avoid duplicates.

Event timestamp

The timestamp field is used to specify when the event occurred. If not provided, the server will use the current time.

Batching events

You can send multiple events in a single API request by batching them together. This can help reduce the number of network requests and improve performance. When batching events:

• Make sure to include an idempotency_key for each event to ensure they are processed correctly.
• The maximum number of events that can be sent per batch is 100.
• If any event in the batch is invalid, the entire batch will be rejected to maintain data integrity.