younifyd
Menu

Create Usage

Log a usage record on this subscription add-on

POST/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 Create Usage action (under usage).
  3. Fill in the fields below, then reference the result from later steps as {{createUsage.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`.

Request body

Enter the body as JSON in the step's Body field.

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").

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.

json
{
  "merchant_tag": "string",
  "amount": 0,
  "recording_timestamp": "2025-01-01T00:00:00Z",
  "usage_timestamp": "2025-01-01T00:00:00Z"
}

Response

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

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>

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

ending_quantityinteger

Ending quantity for the tier. This represents a unit amount for unit-priced add ons. Must be left empty if it is the final tier.

unit_amountnumber (float)

Allows up to 2 decimal places. Optionally, override the tiers' default unit amount. If add-on's `add_on_type` is `usage` and `usage_type` is `percentage`, cannot be provided.

unit_amount_decimalstring

Allows up to 9 decimal places. Optionally, override tiers' default unit amount. If `unit_amount_decimal` is provided, `unit_amount` cannot be provided. If add-on's `add_on_type` is `usage` and `usage_type` is `percentage`, cannot be provided.

usage_percentagestring

(deprecated) -- Use the percentage_tiers object instead.

percentage_tiersarray<object>

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.

ending_amountnumber (float)

Ending amount for the tier. Allows up to 2 decimal places. Must be left empty if it is the final tier.

usage_percentagestring

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places represented as a string.

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
{
  "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.