Subscriptions — usage records

Unveil your customer's usage details with the Subscriptions Usage Records Export.


Required plan

This feature or setting is available to all customers on any Recurly subscription plan.


The Subscriptions Usage Records Export allows you to acquire individual usage records associated with your customer’s usage-based subscription add-ons. This data is crucial for your finance team to report on pre-billed revenue and enables product and marketing teams to scrutinize customer usage patterns. Note that for an accurate revenue reflection, discounts applied at the invoice level should be reviewed in the Adjustments export as they are not depicted here.

Access the detailed usage records through the Exports page found under the "Reports" section on your Recurly site.


Plan Filter

All Plans

Get data on all plans with usage-based add-ons.

Monthly Usage Plan

Choose to export usage details of a specific plan’s usage-based add-ons.

Usage-Based Add-On Filter

All Usage-Based Add-Ons

Export records for all associated usage-based add-ons for a chosen plan.

Specific Add-On

Refine your export to records of a singular usage-based add-on in a selected plan.

Date Range Filters

  • Created: Extract records created in Recurly in your preferred time span.
  • Modified: Attain records of updates done in Recurly in a chosen time window.
  • Usage Timestamp: To understand the utilization in a period, pull records based on usage timestamps.
  • Recording Timestamp: Retrieve records documented in your system within a selected time frame.
  • Billed: Gain insights into the usage records billed in a particular duration.

Exports table

Download Button Download our complete export schema

To help you identify and organize information effectively, the export provides a structured table that contains the following columns:

Column NameExampleDescription
usage_id400527199884543703Unique ID of the usage record.
account_code239485723046981734Account code of the associated customer.
subscription_id3598f5c395fc7e2f4a4eaa4888b9784bID representing the relevant usage-based add-on subscription.
plan_codemega_videoCode of the associated subscription plan.
add_on_codevideo_streamingCode identifying the subscription add-on that the usage record belongs to.
subscription_currencyUSDCurrency used in the subscription and for denoting the unit_amount_in_cents for the add-on.
usage_typeprice, percentageThe pricing model of the usage-based add-on: either "price per unit" or "percentage of an amount".
unit_amount_in_cents60For "price" usage type, indicates the price per usage unit in cents.
usage_percentage4.5For "percentage" usage type, shows the percentage of the billed monetary amount.
measured_unit_internal_namebandwith_streamingInternal name of the applicable measured unit.
measured_unit_display_nameGBDisplay name of the applicable measured unit, describing the "amount" column value.
amount5Units used, represented in cents for "percentage" usage type.
merchant_tag"Rate Lookup ID: 45768456845683435"Custom field to store any relevant information for the usage record.
usage_timestamp2016-04-18 17:00:08 UTCTimestamp of when the units were used, crucial for revenue recognition as it determines the line item date range on the invoice.
recording_timestamp2016-04-18 17:00:08 UTCThe time the usage was recorded in your system; defaults to the usage timestamp if not specified differently.
created_at2016-04-18 17:00:08 UTCThe creation time of the usage record in Recurly.
modified_at2016-04-18 17:00:08 UTCThe modification time in Recurly, possibly when the record was billed or updated before billing.
billed_at2016-04-18 17:00:08 UTCWhen the usage was billed in an invoice.
tier_typeflatSubscription tier type.
unit_amount_in_decimal_cents12345Unit amount in decimal cents.

Version changelog

Version 3 - 1/22/2022

The addition of column unit_amount_in_decimal_cents.

Version 2 - 1/19/2020

Addition of column tier_type.