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.
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
Event timestamp
eventTimestamp determines the billing period in which this usage will be charged.
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.
Event properties
eventPropertiesare arbitrary key-value pairs providing additional metadata for the event.
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.
You can also create test usage events directly in the dashboard by clicking “Add new” and selecting “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.