Subscriptions — usage records - export
Unveil your customer's usage details with the Subscriptions Usage Records Export.
Overview
Required plan
This feature or setting is available to all customers on any Recurly subscription plan.
Definition
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.
Filters
Versions Filter
- The Versions filter allows you to select the version that is most appropriate for your needs. This is based on the version changelog at the bottom of this page.
Plan Filter
- All Plans : Get data on all plans with usage-based add-ons.
- [Specific] 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.
Export On 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.
Time Range Filter
- The Time range filter (dropdown) allows you to view data within a specific period such as last month, year to date or a custom date range. The Start Date and End Date will automatically update based on the value selected in the Time range filter. You can also choose "Between..." in the dropdown, which will allow you to enter a customized date range.
Exports table
To help you identify and organize information effectively, the export provides a structured table that contains the following columns:
| Column Name | Example | Description | |
|---|---|---|---|
| usage_id | 400527199884543703 | Unique ID of the usage record. | |
| account_code | 239485723046981734 | Account code of the associated customer. | |
| subscription_id | 3598f5c395fc7e2f4a4eaa4888b9784b | ID representing the relevant usage-based add-on subscription. | |
| plan_code | mega_video | Code of the associated subscription plan. | |
| add_on_code | video_streaming | Code identifying the subscription add-on that the usage record belongs to. | |
| subscription_currency | USD | Currency used in the subscription and for denoting the unit_amount_in_cents for the add-on. | |
| usage_type | price, percentage | The pricing model of the usage-based add-on: either "price per unit" or "percentage of an amount". | |
| unit_amount_in_cents | 60 | For "price" usage type, indicates the price per usage unit in cents. | |
| usage_percentage | 4.5 | For "percentage" usage type, shows the percentage of the billed monetary amount. | |
| measured_unit_internal_name | bandwith_streaming | Internal name of the applicable measured unit. | |
| measured_unit_display_name | GB | Display name of the applicable measured unit, describing the "amount" column value. | |
| amount | 5 | Units 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_timestamp | 2016-04-18 17:00:08 UTC | Timestamp of when the units were used, crucial for revenue recognition as it determines the line item date range on the invoice. | |
| recording_timestamp | 2016-04-18 17:00:08 UTC | The time the usage was recorded in your system; defaults to the usage timestamp if not specified differently. | |
| created_at | 2016-04-18 17:00:08 UTC | The creation time of the usage record in Recurly. | |
| modified_at | 2016-04-18 17:00:08 UTC | The modification time in Recurly, possibly when the record was billed or updated before billing. | |
| billed_at | 2016-04-18 17:00:08 UTC | When the usage was billed in an invoice. | |
| tier_type | flat | Subscription tier type. | |
| unit_amount_in_decimal_cents | 12345 | Unit amount in decimal cents. | |
| sub_usage_api_id | e28zov4fw0v2 | Subscription Usage API ID | String |
Version changelog
Version 4 - 2/5/2025
Addition of sub_usage_api_id.
Version 3 - 1/22/2022
The addition of column unit_amount_in_decimal_cents.
Version 2 - 1/19/2020
Addition of column tier_type.
Updated 1 day ago