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 see how it all works together, see the examples, or jump right in with the quick start.

The usage endpoint is strictly rate limited by default. Get in touch with our team to access higher rate limits.

​
Quick start

1. Create a few usage events for a customer:

  • Head to the Usage > Events section in the dashboard and click “New usage event”

  • Select a a customer to assign this event to, and pick the event timestamp to be sometime in the past, e.g. last month

  • Pick an event type, (e.g. “api_call”) and optionally add some event properties as key-value pairs

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

  • From Usage > Metrics, click “New usage metric”

  • Give the metric a name (e.g. “API calls”) and optionally a description

  • Select the event type you defined in step 1 from the drop-down, and select “Count of usage values” as the aggregation type

3. Preview the usage metric calculation:

  • After adding the usage metric, select it from the Metrics table to enter the preview window

  • Select the customer the customer that you generated events for in step 1, and pick a time window to calculate the metric over

  • Click “Calculate”. The preview will show the number of usage events found for the given customer in the selected time window

4. Create a usage-based billing schedule:

  • From the Schedules tab, click “New schedule”

  • Select your customer, and add a new product to the schedule by clicking “Add product > Create new”

  • Select “Linear” as your pricing model

  • Give this product a name (e.g. “API usage”) and select the metric you created in step 2 as the “Usage metric”

  • Pick a price per unit, which is the amount to be charged for each usage event

  • Select a start date in the past for the billing schedule, covering the period you generated events for. Click “Start schedule”

5. Generate usage-based invoices:

  • Navigate to the Invoices tab to see the backdated invoices for the billing schedule you just created

  • Click on one of the invoices to see a usage chart and the associated charges

  • 🎉

​
Frequently Asked Questions (FAQ)

​
How do customerEventIds work?

Sequence operates under the general principle that multiple events with the same customerEventId can be submitted, but only the latest event for each customerEventId is included in usage metric calculations. “Latest” here is relative to the time at which the usage metric is calculated. This is usually “now”, but could also be set to a time in the past, in which case the calculation reflects the state of the world at that point in time.

​
Is it possible to send events with a back-dated consumption timestamp and re-calculate billing of the previous or the current month?

Yes. Note that you can only recalculate invoices/bills that have not been issued to a customer yet, so this won’t affect an invoice that has already been issued. You can however recreate the billing schedule and invoice should you need to ‘re-bill’ for an already billed period.

​
Can events be deleted via the UI or API and then re-calculate the billing?

At the moment this is only supported via API. Sequence does not explicitly support deleting events via the API, but any past event can be overwritten by resubmitting the event with the same customerEventId. If needed, our support team can also delete events for you.

​
Does the customerEventId field act like an idempotency key?

While not strictly an idempotency key, it is functionally similar. Sending multiple events with the same customerEventId will result in distinct objects in Sequence, but only the latest event will be considered for the purpose of usage metric calculations. If you send 2 events with the same customerEventId Sequence will respond with 200 (as long as the events are valid) and distinct object IDs in the response. The behaviour is the same whether the event data is identical or not. If you send 2 events with the same customerEventId but with different values Sequence will only take into account the latest event.