API Reference

Prices

Price objects define the cost and billing cycle for a Product. They are attached to Products and determine how much and how often to charge a customer. For instance, a single Product like a software service could have multiple Prices, representing different currencies, billing intervals (monthly vs. yearly), or tiers (basic vs. premium).
Before creating a Price, you must first have a Product to attach it to.
The Price Object#A Price object contains all the details about the pricing structure.
Object Properties
Attribute
Type
Description
id
string
Unique identifier for the price object.
product_id
string
The ID of the product this price is associated with.
active
boolean
Whether the price can be used for new purchases. Defaults to true.
currency_id
string
The ID of the default currency.
currency
object
The full currency object associated with this price.
nickname
string
An internal-facing name for the price, which can be displayed to customers.
type
string
One of one_time or recurring depending on whether the price is for a one-time purchase or a subscription.
unit_amount
string
The unit amount in the smallest currency unit (e.g., cents for USD).
recurring
object
For recurring prices, this hash contains the billing interval information. See details below.
lookup_key
string
A unique, user-defined key that can be used to retrieve the price.
metadata
object
A set of key-value pairs that you can attach to an object. Useful for storing additional information.
product
object
The expanded Product object this price belongs to.
quantity_available
number
The total number of units available for sale.
quantity_sold
number
The number of units that have been sold.
quantity_limit_per_checkout
number
The maximum number of units that can be purchased in a single checkout.
created_at
string
Timestamp of when the object was created.
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. For example, interval: 'month' and interval_count: 3 bills every 3 months.
meter_id
string
Optional. The ID of a Meter to associate with this price for usage-based billing.
Create a Price#Creates a new price object for a product. A price can be for a one-time payment or a recurring subscription.
Parameters
Name
Type
Description
product_id
string
Required. The ID of the product the price belongs to.
unit_amount
number
Required. The price in the currency's main unit (e.g., 10.99 for $10.99).
currency_id
string
Required. The ID of the currency for this price.
type
string
The type of billing. Can be one_time or recurring. Defaults to one_time.
recurring
object
Required if type is recurring. An object specifying the billing cycle. See Recurring Object Properties above.
active
boolean
Whether the price is active. Defaults to true.
nickname
string
A nickname for the price, for internal use.
lookup_key
string
A unique string to reference the price.
metadata
object
Key-value data to store with the price. If the associated product is of type credit, this must contain a credit_config object.
currency_options
array
An array of objects to specify different unit amounts for other currencies.
quantity_available
number
The number of units available for this price.
quantity_limit_per_checkout
number
The maximum quantity that can be purchased in a single checkout.
Returns
Returns the newly created Price object.
Example
import payment from '@blocklet/payment-js';

async function createRecurringPrice() {
  try {
    const price = await payment.prices.create({
      product_id: 'prod_xxxxxxxxxxxxxx',
      unit_amount: 19.99,
      currency_id: 'usd_xxxxxxxxxxxxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
      },
      nickname: 'Monthly Premium Plan',
    });
    console.log('Price created:', price);
  } catch (error) {
    console.error('Error creating price:', error.message);
  }
}

createRecurringPrice();Example Response
{
  "id": "price_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "active": true,
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "nickname": "Monthly Premium Plan",
  "type": "recurring",
  "unit_amount": "1999",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter_id": null
  },
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "name": "Premium Service"
  },
  "currency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "US Dollar"
  }
}Retrieve a Price#Retrieves the details of an existing price.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the price to retrieve.
Returns
Returns the retrieved Price object.
Example
import payment from '@blocklet/payment-js';

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

getPrice('price_xxxxxxxxxxxxxx');Example Response
{
  "id": "price_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "active": true,
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "nickname": "Monthly Premium Plan",
  "type": "recurring",
  "unit_amount": "1999",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  }
}Update a Price#Updates the specified price by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Some fields, such as unit_amount, cannot be updated if the price has been used in a transaction (i.e., it is locked). However, attributes like nickname and metadata can always be updated.
Parameters
Name
Type
Description
id
string
Required. The ID of the price to update.
nickname
string
An updated nickname for the price.
metadata
object
A new set of key-value pairs. Note that this will replace the entire metadata object.
active
boolean
Whether the price is active. Setting this to false is equivalent to archiving the price.
lookup_key
string
An updated lookup key. Must be unique.
description
string
An updated description for the price.
Returns
Returns the updated Price object.
Example
import payment from '@blocklet/payment-js';

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

updatePrice('price_xxxxxxxxxxxxxx');Example Response
{
  "id": "price_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "active": true,
  "nickname": "Updated Premium Plan Nickname",
  "metadata": {
    "order_id": "6735"
  }
}List all Prices#Returns a paginated list of your prices.
Parameters
Name
Type
Description
active
boolean
Only return prices with the given active status.
type
string
Only return prices of the given type (one_time or recurring).
currency_id
string
Only return prices for the given currency ID.
product_id
string
Only return prices for the given product ID.
lookup_key
string
Only return prices with the given 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 an object containing a list of prices and pagination details.
Example
import payment from '@blocklet/payment-js';

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

listPrices();Example Response
{
  "count": 1,
  "list": [
    {
      "id": "price_xxxxxxxxxxxxxx",
      "product_id": "prod_xxxxxxxxxxxxxx",
      "active": true,
      "nickname": "Monthly Premium Plan",
      "type": "recurring"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}Search Prices#Returns a list of prices that match a search query.
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 an object containing a list of prices that match the query.
Example
import payment from '@blocklet/payment-js';

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

searchPrices();Archive a Price#Deactivates a price, preventing it from being used in new checkouts or subscriptions. Existing subscriptions with this price are not affected.
Parameters
Name
Type
Description
id
string
Required. The ID of the price to archive.
Returns
Returns the archived Price object with active set to false.
Example
import payment from '@blocklet/payment-js';

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

archivePrice('price_xxxxxxxxxxxxxx');Example Response
{
  "id": "price_xxxxxxxxxxxxxx",
  "active": false,
  "nickname": "Monthly Premium Plan"
}Delete a Price#Permanently deletes a price. This action cannot be undone. It is only possible to delete a price that has not been used in any transactions or is otherwise locked.
Parameters
Name
Type
Description
id
string
Required. The ID of the price to delete.
Returns
Returns the deleted Price object.
Example
import payment from '@blocklet/payment-js';

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

deletePrice('price_yyyyyyyyyyyyyy');Example Response
{
  "id": "price_yyyyyyyyyyyyyy"
}Update Inventory#Updates the sold quantity for a price. This is useful for managing stock levels for products with limited availability.
Parameters
Name
Type
Description
id
string
Required. The ID of the price.
quantity
number
Required. The amount to increment or decrement. Must be a positive integer.
action
string
Required. Specifies the inventory action. Must be either increment or decrement.
Returns
Returns the updated Price object.
Example
import payment from '@blocklet/payment-js';

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

updateInventory('price_xxxxxxxxxxxxxx');Example Response
{
  "id": "price_xxxxxxxxxxxxxx",
  "quantity_sold": 5,
  "quantity_available": 100
}This concludes the overview of managing prices with the SDK.

Name	Type	Description
`product_id`	`string`	Required. The ID of the product the price belongs to.
`unit_amount`	`number`	Required. The price in the currency's main unit (e.g., 10.99 for $10.99).
`currency_id`	`string`	Required. The ID of the currency for this price.
`type`	`string`	The type of billing. Can be `one_time` or `recurring`. Defaults to `one_time`.
`recurring`	`object`	Required if `type` is `recurring`. An object specifying the billing cycle. See Recurring Object Properties above.
`active`	`boolean`	Whether the price is active. Defaults to `true`.
`nickname`	`string`	A nickname for the price, for internal use.
`lookup_key`	`string`	A unique string to reference the price.
`metadata`	`object`	Key-value data to store with the price. If the associated product is of type `credit`, this must contain a `credit_config` object.
`currency_options`	`array`	An array of objects to specify different unit amounts for other currencies.
`quantity_available`	`number`	The number of units available for this price.
`quantity_limit_per_checkout`	`number`	The maximum quantity that can be purchased in a single checkout.

Name	Type	Description
`id`	`string`	Required. The ID of the price to update.
`nickname`	`string`	An updated nickname for the price.
`metadata`	`object`	A new set of key-value pairs. Note that this will replace the entire metadata object.
`active`	`boolean`	Whether the price is active. Setting this to `false` is equivalent to archiving the price.
`lookup_key`	`string`	An updated lookup key. Must be unique.
`description`	`string`	An updated description for the price.

Name	Type	Description
`active`	`boolean`	Only return prices with the given active status.
`type`	`string`	Only return prices of the given type (`one_time` or `recurring`).
`currency_id`	`string`	Only return prices for the given currency ID.
`product_id`	`string`	Only return prices for the given product ID.
`lookup_key`	`string`	Only return prices with the given lookup key.
`page`	`number`	The page number for pagination. Defaults to 1.
`pageSize`	`number`	The number of items per page. Defaults to 20.

Name	Type	Description
`id`	`string`	Required. The ID of the price.
`quantity`	`number`	Required. The amount to increment or decrement. Must be a positive integer.
`action`	`string`	Required. Specifies the inventory action. Must be either `increment` or `decrement`.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Prices

The Price Object#

Create a Price#

Retrieve a Price#

Update a Price#

List all Prices#

Search Prices#

Archive a Price#

Delete a Price#

Update Inventory#

Products

Payment Intents

Attribute	Type	Description
`id`	string	Unique identifier for the price object.
`product_id`	string	The ID of the product this price is associated with.
`active`	boolean	Whether the price can be used for new purchases. Defaults to `true`.
`currency_id`	string	The ID of the default currency.
`currency`	object	The full currency object associated with this price.
`nickname`	string	An internal-facing name for the price, which can be displayed to customers.
`type`	string	One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a subscription.
`unit_amount`	string	The unit amount in the smallest currency unit (e.g., cents for USD).
`recurring`	object	For recurring prices, this hash contains the billing interval information. See details below.
`lookup_key`	string	A unique, user-defined key that can be used to retrieve the price.
`metadata`	object	A set of key-value pairs that you can attach to an object. Useful for storing additional information.
`product`	object	The expanded Product object this price belongs to.
`quantity_available`	number	The total number of units available for sale.
`quantity_sold`	number	The number of units that have been sold.
`quantity_limit_per_checkout`	number	The maximum number of units that can be purchased in a single checkout.
`created_at`	string	Timestamp of when the object was created.

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. For example, `interval: 'month'` and `interval_count: 3` bills every 3 months.
`meter_id`	string	Optional. The ID of a Meter to associate with this price for usage-based billing.

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.