Metrics & Events
Usage Events

Sequence models usage as a series of events, each capturing an interaction of a customer with your product. A usage event in Sequence looks like this:

{
  "eventType": "transaction_processed",
  "customerAlias": "customer-id-2H4u5BBwBWsS5V2sroRFqJfTXpW",
  "eventTimestamp": "2022-10-01T00:00:00Z",
  "customerEventId": "event-id-H4twuTWpYx1rkd8OMTki2hTUcZ",
  "eventProperties": {
    "amount": 500,
    "currency": "GBP",
    "method": "bank_transfer"
  }
}

Event type

eventType is the top-level category for the event, and describes at a high level what happened. Only events of the same type can be aggregated together via usage metrics.

As a rule of thumb, use different event types for events that could result in different charges for the customer

Customer

customerAlias identifies the customer that the event belongs to. It can be either:

  • The ID of a Sequence customer object
  • One of the customer aliases associated with a Sequence customer object
Customer aliases allow you to reference customers via your own internal IDs instead of the Sequence ID when sending usage data to Sequence, which is sometimes more convenient. You can also use customer aliases to represent relationships between users of your product and customers paying for that usage, if those are separate entities in your system. Customer aliases should be globally unique.

Event timestamp

eventTimestamp determines the billing period in which this usage will be charged.

Timestamps must be strings in ISO 8601 format, e.g. “2019-09-07T15:00:00Z”

Customer event id

customerEventId is a unique identifier for the event that you can optionally set, and is otherwise auto-generated by Sequence. If multiple events with the same customer event ID are received, only the last one will contribute to usage metric calculations.

Use customer event IDs for debugging, as idempotency keys when retrying the same event multiple times, or to intentionally override previously sent events

Event properties

  • eventProperties are arbitrary key-value pairs providing additional metadata for the event.
Use properties to express quantities to be aggregated in usage metrics (such as transaction amount) or categorical attributes for filtering/grouping (such as a payment method)

Designing events

While usage events are the foundation of usage-based billing, it’s important to note that this data is purely about usage, and is not intended to carry any information about how you charge your customers – that’s the job of usage metrics and prices. Feel free to use as many event types and properties as needed to appropriately describe how your customers use your product, even if some of this data is not currently used for billing. This way, you will

  • get a more comprehensive view of your usage via Sequence insights
  • unlock opportunities to evolve your pricing further down the line with low effort, and even backtest pricing changes against historical usage data

To stay flexible, define events at the most granular level possible. For example, if you are already tracking the monthly usage for each of your customers in your internal systems, it might be tempting to upload this pre-aggregated data to Sequence once a month. This approach can be reasonable in some scenarios, but will cause friction when iterating your pricing in ways that require changes to the aggregation logic, like switching from a raw count of events to a sum of an event property, breaking down events into more granular groups that are priced differently, or changing the billing frequency. On the other hand, sending individual usage events helps make your usage data more generic and keep all your billing logic within Sequence, which allows you to iterate on pricing with just a few clicks in the Sequence dashboard.

Sending events to Sequence

Send events to Sequence programmatically via the API as they happen in your application:

curl --request POST \
     --url https://eu.sequencehq.com/api/usage-events \
     --header 'Authorization: your_token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "eventType": "transaction_processed",
  "customerAlias": "customer-id-2H4u5BBwBWsS5V2sroRFqJfTXpW",
  "eventTimestamp": "2022-10-01T00:00:00Z",
  "customerEventId": "event-id-H4twuTWpYx1rkd8OMTki2hTUcZ",
  "eventProperties": {
    "amount": 500,
    "currency": "GBP",
    "method": "bank_transfer"
  }
}
'

Alternatively, if you prefer uploading usage data manually in batches as csv files, get in touch with our team.

Coming soon If you already track usage data in your internal data stack, Sequence can plug into your data warehouse and automatically pull usage events. Get in touch with the team to learn more.

You can also create test usage events directly in the dashboard by clicking “Add new” and selecting “Usage event”:

Add Usage event

Editing events

Once ingested into Sequence, usage events are immutable – in particular, deleting past events is not currently supported. However, it is possible to effectively override an event by posting a new event with the same customerEventId. The original event will still exist in Sequence, but metric calculations will deduplicate events on customerEventId, keeping the last one received.