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
eventProperties
are arbitrary key-value pairs providing additional metadata for the event.
Designing events
Usage events are the foundation of usage-based billing, but in Sequence they are designed to carry information purely about how your customers use your product, not about how they are charged for it – the latter is the job of usage metrics and prices. Use as many event types and properties as needed to appropriately describe how your customers are interacting with your product, even if some of this data is not not relevant your current pricing model. 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 test pricing changes against historical usage data
To stay flexible, define events at the most granular level possible. For example, if you are already tracking monthly usage at the customer level in your internal systems, you could consider uploading this 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, differentiating your pricing over more granular groups, 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
There are 3 ways you can send usage 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"
}
}
'
- Set up an automatic import from your data warehouse
- Upload usage data manually in batches as CSV files. Get in touch with the Sequence team to get a CSV template to help you format your data.
Before starting to ingest your production data, you can also create test usage events directly in the dashboard by clicking “Add new” and selecting “Usage event”:

Editing events
Because previously ingested events may have contributed to issued invoices, Sequence generally
treats usage events as immutable. It is however possible to
effectively override an event by posting a new event with the same customerEventId
.
The original event will still exist in Sequence, but future metric calculations will only take the
last received event into account.