Metrics & Events

If your pricing model has a variable component based on usage for one or more products you can express that in Sequence via usage events and usage metrics.

Usage events are basic units of product usage – for example: an API call, a transaction processed, a user session. Each usage event belongs to one of your customers and includes contextual information in the form of the event type and properties.

Usage metrics measure overall usage by aggregating multiple usage events – for example: the total number of API calls, transaction volume, active users. Metrics are scoped to a specific customer and time period, and can include filters and breakdowns based on event properties.

Sequence updates usage metrics in real time as customers use your product. At the end of each billing period, the total usage for each of your customers is combined with a price to calculate the corresponding charge on the invoice. To get a sense of how it all works together, see the examples, or jump right in with the quickstart.


1. Create a few usage events for a customer:

  • From the Customers section, select a customer for which you have set up a customer alias. You will need this alias when creating events
  • Head to the Usage section in the dashboard and click on Add new > Usage event to add a test event (you can also use the Usage Event API endpoint to do this)
  • Pick an event type (e.g. “api_call”) and type the customer alias for the customer you selected. Pick the event time to be sometime in the past, e.g. last month
  • Repeat the last step a few times to generate a few test events. You will see them appear on the events table

2. Create a usage metric to aggregate the events:

  • Click on Add new > Usage metric
  • Give the metric a name (e.g. “API calls”), and enter the event type from the events you created in step 1
  • Select “COUNT” as the aggregation type

3. Create a usage-based plan for this metric:

  • Click on Add new > Plan
  • Give the plan a name (e.g. “Usage-based plan (API calls)”) and click on “Add products”
  • Select “Linear pricing” as your pricing model
  • Give this product a name (e.g. “API usage”) and select the metric you just created as the “Usage metric”

4. Create a billing schedule for your customer and usage-based plan:

  • Click on Add new > Schedule
  • Select the customer you originally selected and the plan you just created
  • Select the start and end date for the schedule to include the usage events you previously created (e.g. pick the start date as 2 months ago, and the schedule duration as 1 year).
  • Pick the day of the month when you want invoices to be generated (e.g. the 1st of each month)

5. Generate usage-based invoices:

  • Navigate to the Invoices tab in the Billing section
  • Wait a few seconds while backdated invoices are generated
  • Click into one of the invoices to see usage-based charges
  • 🎉