younifyd
Menu

List Usage

List a subscription add-on's usage records

GET/subscriptions/{subscription_id}/add_ons/{add_on_id}/usage

Use it in a workflow

  1. Add a step and choose the Recurly connector.
  2. Pick the List Usage action (under usage).
  3. Fill in the fields below, then reference the result from later steps as {{listUsage.response.data}}.

Request

Path parameters

subscription_idstringrequired

Subscription ID or UUID. For ID no prefix is used e.g. `e28zov4fw0v2`. For UUID use prefix `uuid-`, e.g. `uuid-123457890`.

add_on_idstringrequired

Add-on ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-gold`.

Query parameters

idsarray<string>

Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. `ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6`. **Important notes:** * The `ids` parameter cannot be used with any other ordering or filtering parameters (`limit`, `order`, `sort`, `begin_time`, `end_time`, etc) * Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request. * Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

limitinteger

Limit number of records 1-200.

Default 20

orderstring

Sort order.

One ofascdescDefault "desc"

sortstring

Sort field. You *really* only want to sort by `usage_timestamp` in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

One ofrecorded_timestampusage_timestampDefault "usage_timestamp"

begin_timestring (date-time)

Inclusively filter by begin_time when `sort=usage_timestamp` or `sort=recorded_timestamp`. **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

end_timestring (date-time)

Inclusively filter by end_time when `sort=usage_timestamp` or `sort=recorded_timestamp`. **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

billing_statusstring

Filter by usage record's billing status

One ofunbilledbilledallDefault "unbilled"

Response

Returns 200 with an object. Read it in later steps with {{listUsage.response.data.<field>}}.

objectstring

Will always be List.

has_moreboolean

Indicates there are more results on subsequent pages.

nextstring

Path to subsequent page of results.

dataarray<object>
idstring
objectstring
merchant_tagstring

Custom field for recording the id in your own system associated with the usage, so you can provide auditable usage displays to your customers using a GET on this endpoint.

amountnumber (float)

The amount of usage. Can be positive, negative, or 0. If the Decimal Quantity feature is enabled, this value will be rounded to nine decimal places. Otherwise, all digits after the decimal will be stripped. If the usage-based add-on is billed with a percentage, your usage should be a monetary amount formatted in cents (e.g., $5.00 is "500").

usage_typestring

Type of usage, returns usage type if `add_on_type` is `usage`.

One ofpricepercentage

tier_typestring

The pricing model for the add-on. For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our [Guide](https://recurly.com/developers/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models.

One offlattieredstairstepvolumeDefault "flat"

tiersarray<object>4 fields

The tiers and prices of the subscription based on the usage_timestamp. If tier_type = flat, tiers = []

percentage_tiersarray<object>2 fields

The percentage tiers of the subscription based on the usage_timestamp. If tier_type = flat, percentage_tiers = []. This feature is currently in development and requires approval and enablement, please contact support.

measured_unit_idstring

The ID of the measured unit associated with the add-on the usage record is for.

recording_timestampstring (date-time)

When the usage was recorded in your system.

usage_timestampstring (date-time)

When the usage actually happened. This will define the line item dates this usage is billed under and is important for revenue recognition.

usage_percentagenumber (float)

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.

unit_amountnumber (float)
unit_amount_decimalstring

Unit price that can optionally support a sub-cent value.

billed_atstring (date-time)

When the usage record was billed on an invoice.

created_atstring (date-time)

When the usage record was created in Recurly.

updated_atstring (date-time)

When the usage record was billed on an invoice.

json
{
  "object": "string",
  "has_more": false,
  "next": "string",
  "data": [
    {
      "id": "string",
      "object": "string",
      "merchant_tag": "string",
      "amount": 0,
      "usage_type": "price",
      "tier_type": "flat",
      "tiers": [
        {
          "ending_quantity": 0,
          "unit_amount": 0,
          "unit_amount_decimal": "string",
          "usage_percentage": "string"
        }
      ],
      "percentage_tiers": [
        {
          "ending_amount": 0,
          "usage_percentage": "string"
        }
      ],
      "measured_unit_id": "string",
      "recording_timestamp": "2025-01-01T00:00:00Z",
      "usage_timestamp": "2025-01-01T00:00:00Z",
      "usage_percentage": 0
    }
  ]
}

Need more? See the Recurly guide for connection setup and behaviour shared by every action.

Was this page helpful?
List Usage — Recurly — Documentation