The Price object

Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. Products help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme. For example, you might have a single “Pro pass" product that has prices for $10 USDC/month, $100 USDC/year, and $9 USDC once-off.

Stripe API equivalent
ENDPOINTS
POST /v1/prices
POST /v1/prices/:id
GET /v1/prices/:id
GET /v1/prices
DELETE /v1/prices/:id

Attributes

id string

Unique identifier for the object.

active boolean

Whether the price can be used for new purchases.

currency enum

ISO currency code, in lowercase. Should always be usdc.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

nicknamenullable string

A brief description of the price, hidden from customers.

product string

The ID of the product this price is associated with.

recurringnullable object

The recurring components of a price such as interval and usage_type.

tax_behaviornullable enum

Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

Possible enum values
inclusiveTax is included in the price.
exclusiveTax is added on top of the price.
unspecifiedNo explicit tax behavior is set.
type enum

One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.

Possible enum values
one_timeA one-time purchase price.
recurringA subscription (recurring) price.
unit_amountnullable number

The unit amount in the smallest currency unit to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit.

More attributes

THE PRICE OBJECT
{
  "id": "price_z_yXmLn04Bpw9Wbjx2",
  "object": "price",
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1778605292,
  "currency": "usdc",
  "custom_unit_amount": null,
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": "Pro Plan Price",
  "product": "prod_z_oJaYlHpf6YmRzCMm",
  "recurring": {
    "aggregate_usage": null,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": null,
  "type": "recurring",
  "unit_amount": 1000,
  "unit_amount_decimal": "1000"
}

Create a price

Creates a new price object.

Stripe API equivalent
ENDPOINTS
POST /v1/prices

Parameters

currency enum Required

ISO currency code, in lowercase. Should always be usdc.

active boolean

Whether the price can be used for new purchases.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

nickname string

A brief description of the price, hidden from customers.

product string Required unless product_data is provided

The ID of the product this price is associated with.

recurring object

The recurring components of a price such as interval and usage_type.

tax_behavior enum

Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

Possible enum values
inclusiveTax is included in the price.
exclusiveTax is added on top of the price.
unspecifiedNo explicit tax behavior is set.
unit_amount number

The unit amount in the smallest currency unit to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit.

More attributes

Returns

Returns a Price object if the call succeeds.

POST/v1/prices
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.yourdomain.com');

const price = await zoneless.prices.create({
  currency: 'usdc',
  unit_amount: 1000,
  recurring: {
    interval: 'month',
  },
  product_data: {
    name: 'Pro Plan Price',
  },
});
RESPONSE
{
  "id": "price_z_yXmLn04Bpw9Wbjx2",
  "object": "price",
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1778605292,
  "currency": "usdc",
  "custom_unit_amount": null,
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": "Pro Plan Price",
  "product": "prod_z_oJaYlHpf6YmRzCMm",
  "recurring": {
    "aggregate_usage": null,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": null,
  "type": "recurring",
  "unit_amount": 1000,
  "unit_amount_decimal": "1000"
}

Update a price

Updates the specific price by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Stripe API equivalent
ENDPOINTS
POST /v1/prices/:id

Parameters

active boolean

Whether the price can be used for new purchases.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

nickname string

A brief description of the price, hidden from customers.

tax_behavior enum

Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

Possible enum values
inclusiveTax is included in the price.
exclusiveTax is added on top of the price.
unspecifiedNo explicit tax behavior is set.

More attributes

Returns

Returns the Price object if the update succeeds.

POST/v1/prices/:id
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.yourdomain.com');

const price = await zoneless.prices.update('price_z_yXmLn04Bpw9Wbjx2', {
  metadata: {
    order_id: '1234',
  },
});
RESPONSE
{
  "id": "price_z_yXmLn04Bpw9Wbjx2",
  "object": "price",
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1778605292,
  "currency": "usdc",
  "custom_unit_amount": null,
  "livemode": false,
  "lookup_key": null,
  "metadata": {
    "order_id": "1234"
  },
  "nickname": "Pro Plan Price",
  "product": "prod_z_oJaYlHpf6YmRzCMm",
  "recurring": {
    "aggregate_usage": null,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": null,
  "type": "recurring",
  "unit_amount": 1000,
  "unit_amount_decimal": "1000"
}

Retrieve a price

Retrieves the price with the given ID.

Stripe API equivalent
ENDPOINTS
GET /v1/prices/:id

Parameters

No parameters.

Returns

Returns a Price object if you provide a valid identifier. Raises an error otherwise.

GET/v1/prices/:id
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.yourdomain.com');

const price = await zoneless.prices.retrieve('price_z_yXmLn04Bpw9Wbjx2');
RESPONSE
{
  "id": "price_z_yXmLn04Bpw9Wbjx2",
  "object": "price",
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1778605292,
  "currency": "usdc",
  "custom_unit_amount": null,
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": "Pro Plan Price",
  "product": "prod_z_oJaYlHpf6YmRzCMm",
  "recurring": {
    "aggregate_usage": null,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": null,
  "type": "recurring",
  "unit_amount": 1000,
  "unit_amount_decimal": "1000"
}

List all prices

Returns a list of prices. The prices are returned in sorted order, with the most recently created prices appearing first.

ENDPOINTS
GET /v1/prices

Parameters

active boolean

Only return prices that are active or inactive (e.g., pass false to list all inactive prices).

currency enum

Only return prices for the given currency.

product string

Only return prices for the given product.

type enum

Only return prices of type recurring or one_time.

Possible enum values
one_time
recurring

More attributes

Returns

A dictionary with a data property that contains an array of up to limit prices. If no more prices are available, the resulting array will be empty.

GET/v1/prices
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.yourdomain.com');

const prices = await zoneless.prices.list({
  limit: 3,
});
RESPONSE
{
  "object": "list",
  "url": "/v1/prices",
  "has_more": false,
  "data": [
  {
    "id": "price_z_yXmLn04Bpw9Wbjx2",
    "object": "price",
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1778605292,
    "currency": "usdc",
    "custom_unit_amount": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": "Pro Plan Price",
    "product": "prod_z_oJaYlHpf6YmRzCMm",
    "recurring": {
      "aggregate_usage": null,
      "interval": "month",
      "interval_count": 1,
      "trial_period_days": null,
      "usage_type": "licensed"
    },
    "tax_behavior": "unspecified",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "recurring",
      "unit_amount": 1000,
      "unit_amount_decimal": "1000"
   }
  ]
}