Products & Prices
Products and Prices are the foundational elements of your catalog in PaymentKit. A Product represents what you sell (e.g., a software subscription, a physical good, or a credit pack), while a Price determines how much and how often you charge for that product. A single product can have multiple prices, allowing for flexible billing models (e.g., monthly vs. yearly subscriptions).
This guide will walk you through managing products and their associated prices using the PaymentKit SDK. For a complete list of all available API methods and parameters, please refer to the Products API Reference and Prices API Reference.
First, let's visualize the relationship between products and prices.
Managing Products#
The payment.products object provides methods to create, retrieve, update, and manage the products in your system.
Create a product#
To create a new product, use the payment.products.create method. You need to provide a name, type, and an optional description.
Parameters
Name | Type | Description |
|---|---|---|
|
| Required. The name of the product, shown to customers. |
|
| An optional description of the product. |
|
| Required. The type of product. Can be |
|
| Whether the product is currently available for purchase. Defaults to |
|
| A set of key-value pairs to store additional information about the object. |
Example: Create a service product
const product = await payment.products.create({
name: 'Test Product',
description: 'Product description',
type: 'service'
});
console.log(product);Example Response
{
"id": "prod_1C3a5E7b9D1f3G5h7I9j1K3m",
"active": true,
"livemode": false,
"locked": false,
"type": "service",
"name": "Test Product",
"description": "Product description",
"images": [],
"features": [],
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}List products#
To retrieve a list of your products, use the payment.products.list method. You can filter and paginate the results.
Parameters
Name | Type | Description |
|---|---|---|
|
| (Optional) Set to |
|
| (Optional) Filter products by name. |
|
| (Optional) The page number for pagination. Defaults to |
|
| (Optional) The number of items per page. Defaults to |
|
| (Optional) Sort order (e.g., |
Example: List active products
const products = await payment.products.list({
active: true,
order: 'name:ASC',
});
console.log(products);Example Response
{
"count": 1,
"list": [
{
"id": "prod_1C3a5E7b9D1f3G5h7I9j1K3m",
"active": true,
"livemode": false,
"type": "service",
"name": "Test Product",
"description": "Product description",
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}
]
}Managing Prices#
Once you have a product, you can create one or more prices for it using the payment.prices object.
Create a price#
A price can be for a one-time purchase or a recurring subscription. For recurring prices, you must specify the billing interval.
Parameters
Name | Type | Description |
|---|---|---|
|
| Required. The ID of the product this price belongs to. |
|
| Required. The type of pricing. Can be |
|
| Required. The price amount as a string. |
|
| Required. The ID of the currency for this price. |
|
| Whether the price is currently available for purchase. Defaults to |
|
| Required if |
|
| The total available quantity of this price. |
|
| The maximum quantity a customer can purchase in a single checkout. |
The recurring Object
Name | Type | Description |
|---|---|---|
|
| Required. The billing frequency. Can be |
|
| Required. The number of intervals between subscription billings (e.g., |
|
| The usage type. Can be |
Example: Create a recurring monthly price
const price = await payment.prices.create({
product_id: 'prod_1C3a5E7b9D1f3G5h7I9j1K3m', // From the product created earlier
type: 'recurring',
unit_amount: '19.99',
currency_id: 'pc_A1b2C3d4E5f6G7h8', // Replace with a valid currency ID
recurring: {
interval: 'month',
interval_count: 1,
usage_type: 'licensed'
}
});
console.log(price);Example Response
{
"id": "price_2D4b6F8c0E2g4H6i8J0k2L4n",
"product_id": "prod_1C3a5E7b9D1f3G5h7I9j1K3m",
"active": true,
"livemode": false,
"type": "recurring",
"billing_scheme": "per_unit",
"unit_amount": "19.99",
"currency_id": "pc_A1b2C3d4E5f6G7h8",
"recurring": {
"interval": "month",
"interval_count": 1,
"usage_type": "licensed"
},
"created_at": "2023-10-27T10:05:00.000Z",
"updated_at": "2023-10-27T10:05:00.000Z"
}Manage price inventory#
For products with limited stock, you can adjust the available quantity of a price using the inventory method. This is useful for managing goods with finite availability.
Parameters
Name | Type | Description |
|---|---|---|
|
| Required. The ID of the price to update. |
|
| Required. The number to increment or decrement the inventory by. |
|
| Required. The action to perform. Must be |
Example: Increase the inventory of a price
const priceId = 'price_2D4b6F8c0E2g4H6i8J0k2L4n';
const updatedPrice = await payment.prices.inventory(priceId, {
quantity: 100,
action: 'increment'
});
console.log(`New quantity available: ${updatedPrice.quantity_available}`);Example Response
{
"id": "price_2D4b6F8c0E2g4H6i8J0k2L4n",
"quantity_available": 100,
"quantity_sold": 0,
// ... other price fields
}Now that you know how to create and manage products and prices, you are ready to start selling them. The next step is to create a checkout experience for your customers. Learn how in the Checkout Sessions guide.