API Reference

Prices

Prices represent the cost of a product and how it's billed. A product can have multiple prices, allowing for different currencies, billing intervals (one-time vs. recurring), and pricing models (per-unit vs. tiered). This API allows you to create and manage these pricing models.
Before creating a price, you must first have a Product to associate it with.
Has one or more
Can be
Can be
Is used in
Defines
Product
Price
One-Time
Recurring
Checkout Session
Billing Interval

The Price Object#A Price object contains all the details about a specific pricing configuration for a product. The expanded version TPriceExpanded also includes the full product and currency objects.
Attribute
Type
Description
id
string
Unique identifier for the price.
product_id
string
The ID of the product this price is for.
nickname
string
An internal-facing name for the price.
active
boolean
Whether the price can be used in new checkouts.
type
`'one_time'
'recurring'`
billing_scheme
`'per_unit'
'tiered'`
unit_amount
string
The unit amount in the smallest currency unit (e.g., cents for USD).
recurring
object
Details for recurring prices. See PriceRecurring type below.
tiers
array
For tiered billing, the tiers structure.
currency_id
string
The three-letter ISO currency code.
quantity_available
number
The available quantity for this price. Null if unlimited.
product
object
(Expanded) The full product object.
currency
object
(Expanded) The full payment currency object.
The PriceRecurring Object#Attribute
Type
Description
interval
`'hour'
'day'
interval_count
number
The number of intervals between subscription billings.
usage_type
`'licensed'
'metered'`
Create a Price#Creates a new price and associates it with a product.
Parameters
Parameter
Type
Description
product_id
string
Required. The ID of the product this price belongs to.
unit_amount
string
Required. A positive integer in the smallest currency unit representing how much to charge.
currency_id
string
Required. The ID of the currency this price is in.
type
`'one_time'
'recurring'`
nickname
string
A brief description of the price, not visible to customers.
active
boolean
Whether the price is active for new purchases. Defaults to true.
recurring
object
Required if type is recurring. An object containing interval and interval_count.
billing_scheme
`'per_unit'
'tiered'`
lookup_key
string
A unique, user-defined key that can be used to retrieve the price.
quantity_available
number
The initial quantity available for this price.
Example
import payment from '@blocklet/payment-js';

async function createRecurringPrice() {
  try {
    const price = await payment.prices.create({
      product_id: 'prod_xxxxxxxxxxxxxx',
      nickname: 'Standard Monthly Plan',
      unit_amount: '2000', // e.g., $20.00
      currency_id: 'cur_xxxxxxxxxxxxxx', // Corresponds to USD
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
      },
    });
    console.log('Price created:', price);
  } catch (error) {
    console.error('Error creating price:', error.message);
  }
}

createRecurringPrice();Example Response
{
  "id": "price_xxxxxxxxxxxxxx",
  "object": "price",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "nickname": "Standard Monthly Plan",
  "active": true,
  "livemode": false,
  "type": "recurring",
  "billing_scheme": "per_unit",
  "unit_amount": "2000",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "currency_id": "cur_xxxxxxxxxxxxxx",
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "name": "My SaaS Product"
  },
  "currency": {
    "id": "cur_xxxxxxxxxxxxxx",
    "name": "US Dollar"
  }
}Retrieve a Price#Retrieves the details of an existing price.
Parameters
Parameter
Type
Description
id
string
Required. The unique identifier of the price to retrieve.
Example
import payment from '@blocklet/payment-js';

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

getPrice('price_xxxxxxxxxxxxxx');Example Response
{
  "id": "price_xxxxxxxxxxxxxx",
  "object": "price",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "nickname": "Standard Monthly Plan",
  "active": true,
  "type": "recurring",
  "unit_amount": "2000",
  "currency_id": "cur_xxxxxxxxxxxxxx"
}Update a Price#Updates the specified price by setting the values of the parameters passed.
Parameters
Parameter
Type
Description
id
string
Required. The ID of the price to update.
nickname
string
A brief description of the price.
active
boolean
Whether the price is active.
lookup_key
string
A unique, user-defined key.
metadata
object
A set of key-value pairs to store with the object.
Example
import payment from '@blocklet/payment-js';

async function updatePrice(priceId) {
  try {
    const price = await payment.prices.update(priceId, {
      nickname: 'Updated Standard Plan Name',
    });
    console.log('Price updated successfully:', price.id);
  } catch (error) {
    console.error('Error updating price:', error.message);
  }
}

updatePrice('price_xxxxxxxxxxxxxx');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.
Parameters
Parameter
Type
Description
active
boolean
Only return prices that are active.
type
`'one_time'
'recurring'`
currency_id
string
Only return prices for the given currency.
product_id
string
Only return prices for the given product.
lookup_key
string
Only return the price with this lookup key.
page
number
The page number for pagination.
pageSize
number
The number of items per page. Defaults to 20.
order
array
The order to sort the results by.
Example
import payment from '@blocklet/payment-js';

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

listPrices();Example Response
{
  "count": 1,
  "list": [
    {
      "id": "price_xxxxxxxxxxxxxx",
      "object": "price",
      "product_id": "prod_xxxxxxxxxxxxxx",
      "nickname": "Standard Monthly Plan",
      "active": true,
      "type": "recurring",
      "unit_amount": "2000"
    }
  ]
}Update Inventory#Increments or decrements the quantity_available for a price. This is useful for managing stock levels.
Parameters
Parameter
Type
Description
id
string
Required. The ID of the price to update inventory for.
quantity
number
Required. The amount to adjust the inventory by. Can be positive or negative.
action
`'increment'
'decrement'`
Example
import payment from '@blocklet/payment-js';

async function decrementInventory(priceId) {
  try {
    const price = await payment.prices.inventory(priceId, {
      quantity: 1,
      action: 'decrement',
    });
    console.log('Inventory updated. New quantity available:', price.quantity_available);
  } catch (error) {
    console.error('Error updating inventory:', error.message);
  }
}

decrementInventory('price_xxxxxxxxxxxxxx');Archive a Price#Deactivates a price, preventing it from being used in new checkouts. Existing subscriptions with this price are not affected.
Parameters
Parameter
Type
Description
id
string
Required. The ID of the price to archive.
Example
import payment from '@blocklet/payment-js';

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

archivePrice('price_xxxxxxxxxxxxxx');Delete a Price#Permanently deletes a price. This action cannot be undone.
Parameters
Parameter
Type
Description
id
string
Required. The ID of the price to delete.
Example
import payment from '@blocklet/payment-js';

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

deletePrice('price_xxxxxxxxxxxxxx');
With products and prices configured, you can now create transactions. Learn more about how to create a customer-facing payment page in the Checkout Sessions guide.

Attribute	Type	Description
`id`	`string`	Unique identifier for the price.
`product_id`	`string`	The ID of the product this price is for.
`nickname`	`string`	An internal-facing name for the price.
`active`	`boolean`	Whether the price can be used in new checkouts.
`type`	`'one_time'	'recurring'`
`billing_scheme`	`'per_unit'	'tiered'`
`unit_amount`	`string`	The unit amount in the smallest currency unit (e.g., cents for USD).
`recurring`	`object`	Details for recurring prices. See `PriceRecurring` type below.
`tiers`	`array`	For tiered billing, the tiers structure.
`currency_id`	`string`	The three-letter ISO currency code.
`quantity_available`	`number`	The available quantity for this price. Null if unlimited.
`product`	`object`	(Expanded) The full product object.
`currency`	`object`	(Expanded) The full payment currency object.

Parameter	Type	Description
`product_id`	`string`	Required. The ID of the product this price belongs to.
`unit_amount`	`string`	Required. A positive integer in the smallest currency unit representing how much to charge.
`currency_id`	`string`	Required. The ID of the currency this price is in.
`type`	`'one_time'	'recurring'`
`nickname`	`string`	A brief description of the price, not visible to customers.
`active`	`boolean`	Whether the price is active for new purchases. Defaults to `true`.
`recurring`	`object`	Required if `type` is `recurring`. An object containing `interval` and `interval_count`.
`billing_scheme`	`'per_unit'	'tiered'`
`lookup_key`	`string`	A unique, user-defined key that can be used to retrieve the price.
`quantity_available`	`number`	The initial quantity available for this price.

Parameter	Type	Description
`id`	`string`	Required. The ID of the price to update.
`nickname`	`string`	A brief description of the price.
`active`	`boolean`	Whether the price is active.
`lookup_key`	`string`	A unique, user-defined key.
`metadata`	`object`	A set of key-value pairs to store with the object.

Parameter	Type	Description
`active`	`boolean`	Only return prices that are active.
`type`	`'one_time'	'recurring'`
`currency_id`	`string`	Only return prices for the given currency.
`product_id`	`string`	Only return prices for the given product.
`lookup_key`	`string`	Only return the price with this lookup key.
`page`	`number`	The page number for pagination.
`pageSize`	`number`	The number of items per page. Defaults to 20.
`order`	`array`	The order to sort the results by.

Parameter	Type	Description
`id`	`string`	Required. The ID of the price to update inventory for.
`quantity`	`number`	Required. The amount to adjust the inventory by. Can be positive or negative.
`action`	`'increment'	'decrement'`

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Prices

The Price Object#

The `PriceRecurring` Object#

Create a Price#

Retrieve a Price#

Update a Price#

List all Prices#

Update Inventory#

Archive a Price#

Delete a Price#

Products

Payment Intents

Attribute	Type	Description
`interval`	`'hour'	'day'
`interval_count`	`number`	The number of intervals between subscription billings.
`usage_type`	`'licensed'	'metered'`