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. 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.

​

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

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:

1. 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"
  }
}
'

2. 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” from Usage > Events.

​

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 same customerEventId. 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 same customerEventId 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).

​

Identifying unmapped customers

Sequence’s usage infrastructure is agnostic to the billing process so you can submit usage events for customers that have not yet been created in Sequence. In that case, the usage events overview will show that the event has no matching customer alias. Once you map the customer alias of the event to a customer, the events can be aggregated as part of a billing run. On the usage events page in the dashboard, you can also filter out events that include a customer alias that is not mapped to any customer record.