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. Think of event types
as mutually incompatible categories that should not be mixed in aggregations. If you have slightly different events that you might want to combine in the same metric, give them the same event type,
and rely on event properties to distinguish them.
As a rule of thumb, events of the same type should have the same set of properties (i.e. the same schema)
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
Use customer aliases to reference customers via your own internal IDs instead of the Sequence ID when sending usage data to Sequence, if that’s your preference.
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 must 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 a transaction amount) or categorical attributes for filtering/grouping (such as a payment method)
Numerical values (such as transaction amount, duration, size, etc) must conform with ISO 31-0. Digits cannot be separated by commas. Points are reserved for use as the decimal sign. Incorrect event properties are not included in usage aggregations.
Designing events
Although usage events are the foundation of usage-based billing, in Sequence they are intended to purely describe product usage, not the corresponding charges – the latter is the job of usage metrics and prices. Use as many event types and properties as needed to suitably describe how your customers are interacting with your product, even if some of this data is not not relevant your current pricing model. Some of this data may not be relevant to your billing today – that’s okay! Having richer events will allow to get a more comprehensive view of your usage in Sequence, unlock opportunities down the line to more easily evolve your pricing, and even test pricing changes against historical data. As a general rule, Sequence works best if you define events at the most granular level possible, i.e. each event corresponding to an individual charge, and letting Sequence handle aggregations. While pre-aggregating on your end at a daily or monthly frequency can be reasonable in some scenarios, it will generally 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 2 ways you can send usage events to Sequence:- Send events to Sequence programmatically via the API as they happen in your application:
If you are uploading a large number of events programmatically, we recommend adding concurrency
to your script for better performance.
- 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.

Editing events
Because previously ingested events may have contributed to issued invoices, usage events are currently treated as immutable in Sequence. It is however possible to effectively override an event by posting a new event with the samecustomerEventId
.
The original event will still exist in Sequence, but future metric calculations will only take the
last received event into account.
Deleting events
Events cannot be deleted, however you can overwrite or edit events that are no longer relevant (see above). To void an event, resubmit the event with the samecustomerEventId
and update its customer alias to VOID
. Alternatively, you can also adjust the timestamp to fall outside any billing periods or change the amount
to zero (in the case of a transaction event).