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, 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)

​
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:

  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"
  }
}
'
  1. Set up an automatic import from your data warehouse
  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” and selecting “Usage event”:

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

OverviewUsage metrics