The Price Object

A price object represents a price added to a Variant.

When a variant’s price is changed a new price object is created. All old prices are retained.

A price belongs to a Variant and can have many Subscription Items and Usage records.

Attributes

variant_id

The ID of the variant this price belongs to.

scheme

The pricing model for this price. One of:

standard
package
graduated
volume

usage_aggregation

The type of usage aggregation in use if usage-based billing is activated. One of:

sum - Sum of usage during period
last_during_period - Most recent usage during a period
last_ever - Most recent usage
max - Maximum usage during period

Will be null if usage-based billing is not activated on this price’s variant.

unit_price

A positive integer in cents representing the price.

Not used for volume and graduated pricing (tier data is used instead).

If usage_aggregation is enabled for this price, unit_price will be null and unit_price_decimal will be used instead.

unit_price_decimal

A positive decimal string in cents representing the price.

Not used for volume and graduated pricing (tier data is used instead).

If usage_aggregation is not enabled for this price, unit_price_decimal will be null and unit_price will be used instead.

setup_fee_enabled

A boolean indicating if the price has a setup fee.

Will be null for non-subscription pricing.

setup_fee

A positive integer in cents representing the setup fee.

Will be null for non-subscription pricing.

package_size

The number of units included in each package when using package pricing.

Will be 1 for standard, graduated and volume pricing.

tiers

A list of pricing tier objects when using volume and graduated pricing.

Tiers have three values:

last_unit - The top limit of this tier. Will be an integer or "inf" (for “infinite”) if this is the highest-level tier.
unit_price - A positive integer in cents representing the price of each unit. Will be null if usage-based billing is activated on this price’s variant.
unit_price_decimal - A positive decimal string in cents representing the price of each unit. Will be null if usage-based billing is not activated on this price’s variant.
fixed_fee - An optional fixed fee charged alongside the unit price.

Will be null for standard and package pricing.

renewal_interval_unit

If the price’s variant is a subscription, the billing interval. One of:

day
week
month
year

Will be null if the product is not a subscription.

renewal_interval_quantity

If the price’s variant is a subscription, this is the number of intervals (specified in the renewal_interval_unit attribute) between subscription billings.

For example, renewal_interval_unit=month and renewal_interval_quantity=3 bills every 3 months.

Will be null if the product is not a subscription.

trial_interval_unit

The interval unit of the free trial. One of

day
week
month
year

Will be null if there is no trial.

trial_interval_quantity

The interval count of the free trial. For example, a variant with trial_interval_unit=day and trial_interval_quantity=14 would have a free trial that lasts 14 days.

Will be null if there is no trial.

min_price

If category is pwyw, this is the minimum price this variant can be purchased for, as a positive integer in cents.

Will be null for all other categories.

suggested_price

If category is pwyw, this is the suggested price for this variant shown at checkout, as a positive integer in cents.

Will be null for all other categories.

tax_code

The product’s tax category. One of:

eservice
ebook
saas

created_at

An ISO 8601 formatted date-time string indicating when the object was created.

updated_at

An ISO 8601 formatted date-time string indicating when the object was last updated.

{
  "type": "prices",
  "id": "1",
  "attributes": {
    "variant_id": 1,
    "category": "subscription",
    "scheme": "graduated",
    "usage_aggregation": null,
    "unit_price": 999,
    "unit_price_decimal": null,
    "setup_fee_enabled": false,
    "setup_fee": null,
    "package_size": 1,
    "tiers": [
      {
        "last_unit": 2,
        "unit_price": 10000,
        "unit_price_decimal": null,
        "fixed_fee": 1000
      },
      {
        "last_unit": "inf",
        "unit_price": 1000,
        "unit_price_decimal": null,
        "fixed_fee": 1000
      }
    ],
    "renewal_interval_unit": "year",
    "renewal_interval_quantity": 1,
    "trial_interval_unit": "day",
    "trial_interval_quantity": 30,
    "min_price": null,
    "suggested_price": null,
    "tax_code": "eservice",
    "created_at": "2023-05-24T14:15:06.000000Z",
    "updated_at": "2023-06-24T14:44:38.000000Z"
  }
}

← List all variants

Retrieve a price →

Was this page helpful?