Prices

A Price object defines how much and how often to charge for a specific product. It associates a price amount and currency with a Product. For example, a product might have multiple prices, each in a different currency or with a different billing interval.

This document details how to manage Price objects using the SDK.

The Price Object#

A Price object contains all the details about the pricing model for a product.

Attribute	Type	Description
id	string	Unique identifier for the price object.
product_id	string	The ID of the product this price is associated with.
product	object	The expanded Product object.
active	boolean	Whether the price can be used for new purchases.
currency_id	string	The ID of the default currency for this price.
currency	object	The expanded PaymentCurrency object.
nickname	string	A brief description of the price, displayed to customers.
type	string	One of one_time or recurring.
unit_amount	string	The price in the smallest currency unit (e.g., cents for USD).
recurring	object	For recurring prices, this hash contains billing interval information. See details below.
lookup_key	string	A unique, user-defined key to retrieve the price.
metadata	object	A set of key-value pairs that you can attach to an object.
currency_options	array	Specifies different pricing for multiple currencies.
quantity_available	number	The total available quantity for this price. 0 means unlimited.
quantity_sold	number	The number of units sold.
quantity_limit_per_checkout	number	The maximum quantity a customer can purchase in a single checkout. 0 means no limit.
upsell	object	Configuration for upselling to another price.

The recurring Object Properties

Attribute	Type	Description
interval	string	The frequency at which a subscription is billed. One of day, week, month, or year.
interval_count	number	The number of intervals between subscription billings.
meter_id	string	The ID of the meter used for usage-based billing.

Create a Price#

Creates a new price for an existing product.

async function createPrice() {
  try {
    const price = await payment.prices.create({
      product_id: 'prod_xxxxxxxxxxxxxx',
      unit_amount: 1500, // e.g., $15.00
      currency_id: 'usd_xxxxxxxxxxxxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
      },
      nickname: 'Monthly Pro Plan',
      lookup_key: 'pro_monthly_usd',
    });
    console.log('Price created:', price);
  } catch (error) {
    console.error('Error creating price:', error.message);
  }
}

createPrice();

Parameters#

Name	Type	Description
product_id	string	Required. The ID of the product this price belongs to.
unit_amount	number	Required. The amount to be charged, in the smallest currency unit.
currency_id	string	Required. The ID of the currency for this price.
type	string	The type of pricing. Can be one_time or recurring. Defaults to one_time.
active	boolean	Whether the price is active. Defaults to true.
nickname	string	An internal name for the price.
lookup_key	string	A unique string to reference the price.
recurring	object	An object containing recurring billing information. Required if type is recurring.
currency_options	array	An array of objects to specify prices in different currencies.
metadata	object	Key-value data to store with the price.
quantity_available	number	The total available quantity. Defaults to 0 (unlimited).
quantity_limit_per_checkout	number	The maximum quantity per checkout. Defaults to 0 (no limit).

Returns#

Returns the newly created Price object.

{
  "id": "price_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "active": true,
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "nickname": "Monthly Pro Plan",
  "type": "recurring",
  "unit_amount": "1500",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter_id": null
  },
  "lookup_key": "pro_monthly_usd",
  "metadata": {},
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "name": "Pro Plan"
  },
  "currency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "United States Dollar"
  }
}

Retrieve a Price#

Retrieves the details of an existing price.

async function retrievePrice(priceId) {
  try {
    const price = await payment.prices.retrieve(priceId);
    console.log('Price retrieved:', price);
  } catch (error) {
    console.error('Error retrieving price:', error.message);
  }
}

retrievePrice('price_xxxxxxxxxxxxxx');

Parameters#

Name	Type	Description
id	string	Required. The unique identifier of the price to retrieve. Can also be a lookup_key.

Returns#

Returns the requested Price object.

Update a Price#

Updates an existing price by setting the values of the parameters passed.

async function updatePrice(priceId) {
  try {
    const price = await payment.prices.update(priceId, {
      nickname: 'Updated Pro Plan Nickname',
      metadata: { order_id: '6735' },
    });
    console.log('Price updated:', price);
  } catch (error) {
    console.error('Error updating price:', error.message);
  }
}

updatePrice('price_xxxxxxxxxxxxxx');

Parameters#

Name	Type	Description
id	string	Required. The ID of the price to update. Can also be a lookup_key.
updates	object	An object containing the fields to update. See the create method for a list of updatable fields. Note: Core attributes like unit_amount and recurring cannot be changed if the price has been used (locked).

Returns#

Returns the updated Price object.

List all Prices#

Returns a list of your prices. The prices are returned sorted by creation date, with the most recently created prices appearing first.

async function listPrices() {
  try {
    const prices = await payment.prices.list({
      product_id: 'prod_xxxxxxxxxxxxxx',
      active: true,
      limit: 5,
    });
    console.log('Retrieved prices:', prices.list);
  } catch (error) {
    console.error('Error listing prices:', error.message);
  }
}

listPrices();

Parameters#

Name	Type	Description
active	boolean	Only return prices with this active status.
type	string	Only return prices of this type, e.g., recurring.
currency_id	string	Only return prices for this currency ID.
product_id	string	Only return prices for this product ID.
lookup_key	string	Only return the price with this lookup key.
page	number	The page number for pagination. Defaults to 1.
pageSize	number	The number of items per page. Defaults to 20.

Returns#

Returns a paginated object containing a list of Price objects, the total count, and paging information.

Search Prices#

Searches for prices matching a query string.

async function searchPrices() {
  try {
    const prices = await payment.prices.search({ query: 'Pro Plan' });
    console.log('Search results:', prices.list);
  } catch (error) {
    console.error('Error searching prices:', error.message);
  }
}

searchPrices();

Parameters#

Name	Type	Description
query	string	The search query string.
page	number	The page number for pagination. Defaults to 1.
pageSize	number	The number of items per page. Defaults to 20.

Returns#

Returns a paginated object containing a list of matching Price objects.

Archive a Price#

Archives a price, preventing it from being used in new checkouts. If a price has been used, it's generally better to archive it than to delete it.

async function archivePrice(priceId) {
  try {
    const price = await payment.prices.archive(priceId);
    console.log('Price archived:', price.id, 'Active:', price.active);
  } catch (error) {
    console.error('Error archiving price:', error.message);
  }
}

archivePrice('price_xxxxxxxxxxxxxx');

Parameters#

Name	Type	Description
id	string	Required. The ID of the price to archive. Can also be a lookup_key.

Returns#

Returns the archived Price object with active set to false.

Delete a Price#

Permanently deletes a price. This action cannot be undone. A price cannot be deleted if it has been used in a transaction or is otherwise locked.

async function deletePrice(priceId) {
  try {
    const deletedPrice = await payment.prices.del(priceId);
    console.log('Price deleted:', deletedPrice.id);
  } catch (error) {
    console.error('Error deleting price:', error.message);
  }
}

deletePrice('price_xxxxxxxxxxxxxx');

Parameters#

Name	Type	Description
id	string	Required. The ID of the price to delete. Can also be a lookup_key.

Returns#

Returns the deleted Price object.

Update Inventory#

Manually adjusts the quantity_sold for a price. This is useful for tracking inventory outside of the standard checkout flow.

async function updateInventory(priceId) {
  try {
    // Increment sold quantity by 2
    const price = await payment.prices.inventory(priceId, {
      quantity: 2,
      action: 'increment',
    });
    console.log('Inventory updated. New quantity sold:', price.quantity_sold);
  } catch (error) {
    console.error('Error updating inventory:', error.message);
  }
}

updateInventory('price_xxxxxxxxxxxxxx');

Parameters#

Name	Type	Description
id	string	Required. The ID of the price.
params	object	An object containing inventory adjustment details.

params Object Properties

Name	Type	Description
quantity	number	Required. The amount to adjust the sold quantity by.
action	string	Required. The adjustment action. Must be increment or decrement.

Returns#

Returns the updated Price object with the new quantity_sold value.