The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Subscriptions Usage Records

Subscriptions Usage Records

This export will provide the individual usage records logged for your customer's usage-based subscription add-ons. This export is useful for your finance team trying to report on revenue earned before it is billed, as well as your product and marketing teams who may want to analyze customer usage.

For revenue recognition, be aware that the pricing information in this export is the customer's price and does not reflect any discounts factored in at the invoice level. Please review the Adjustments export for any discounts.

To access the Subscriptions Usage Records export, visit the Exports page under Reports in your Recurly site.

Filters

You have the option to filter the export by plan and specific usage-based add-on:

Plan

Export usage records for all plans with usage-based add-ons or filter down to a specific plan's usage-based add-ons.

Usage-Based Add-On

If a specific plan is selected, you can export all the associated usage-based add-on usage records, or filter down to a specific usage-based add-on in the plan.

Time Range Filter

Created

Pull the date range based on when the usage record was created in Recurly.

Modified

Pull the date range based on when the usage record was updated in Recurly. This could be when the usage record was billed, or if you did an update through the API before it was billed.

Usage Timestamp

Pull the date range based on the usage record's usage_timestamp. Use this option if you want to know what was used in a period, regardless of whether or not it has been billed yet.

Recording Timestamp

Pull the date range based on when the usage record was recorded in your own system.

Billed

Pull the date range based on when the usage record was billed.

Export Contents

Column Name
Example
Description

usage_id

400527199884543703

The unique id of the usage record.

account_code

239485723046981734

The account code of the customer whose usage record this is.

subscription_id

3598f5c395fc7e2f4a4eaa4888b9784b

The subscription id for the usage-based add-on this usage record is for.

plan_code

mega_video

The plan code of the associated subscription.

add_on_code

video_streaming

The add-on code of the usage record's subscription add-on.

subscription_currency

USD

The currency of the subscription, which is also the currency of the unit_amount_in_cents for the add-on.

usage_type

price, percentage

Whether the usage-based add-on has a pricing model of "price per unit" or "percentage of an amount".

unit_amount_in_cents

60

If the usage-based add-on has a usage_type of "price", it will have a unit_amount_in_cents, which is the price per each usage amount. In the example, 60 is equivalent to $0.60 USD

usage_percentage

4.5

If the usage-based add-on has a usage_type of "percentage", it will have a usage_percentage, which is the percentage of the monetary amount charged.

measured_unit_internal_name

bandwith_streaming

The internal name of the associated measured unit.

measured_unit_display_name

GB

The display name of the associated measured unit. This describes the amount column value.

amount

5

The units used. If the usage_type is percentage, this amount is stored as the monetary amount in cents. For example, $5.00 USD would be stored as "500".

merchant_tag

"Rate Lookup ID: 45768456845683435"

The merchant tag for the usage record, which is a custom field where you can store whatever you like.

usage_timestamp

2016-04-18 17:00:08 UTC

The usage timestamp, which is when the units were used. This maps to the line item date range on the invoice when the usage is billed and is important for revenue recognition.

recording_timestamp

2016-04-18 17:00:08 UTC

The recording timestamp, which is when the usage was recorded in your own system. This field will default to match the usage timestamp if a different timestamp is not specified.

created_at

2016-04-18 17:00:08 UTC

When the usage record was created in Recurly.

modified_at

2016-04-18 17:00:08 UTC

When the usage record was updated in Recurly. This could be when the usage record was billed or if an update was made before the usage record was billed.

billed_at

2016-04-18 17:00:08 UTC

When the usage record was billed on an invoice.

Subscriptions Usage Records


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.