API Reference

Products

Products represent the goods, services, or digital items you offer to your customers. Managing products is a foundational step in setting up your payment system. This document details how to use the Payment Kit SDK to create, retrieve, update, list, and manage products.
After defining your products, you'll typically create one or more prices for them. For more information, see the Prices API Reference.
The Product Object#A product object contains all the necessary details about an item you sell.
Attribute
Type
Description
id
string
Unique identifier for the product.
active
boolean
Whether the product is currently available for purchase.
livemode
boolean
true if the object exists in live mode, or false if it exists in test mode.
locked
boolean
Whether the product details can be modified. Defaults to false.
type
string
The product's type. Can be service, good, or credit.
name
string
The product's name, displayed to customers.
description
string
The product's description, displayed to customers.
images
string[]
A list of URLs for product images.
features
object[]
A list of features associated with the product. Each feature object has a name property.
unit_label
string
An optional label for a single unit of the product.
default_price_id
string
The ID of the default price for this product.
metadata
object
A set of key-value pairs for storing additional information.
statement_descriptor
string
An optional descriptor that appears on customer bank statements.
created_at
Date
The timestamp when the product was created.
updated_at
Date
The timestamp of the last update.
Create a Product#Creates a new product. You can also create associated prices in the same request.
Parameters
Name
Type
Description
name
string
Required. The product's name.
type
string
Required. The product type, such as 'service' or 'good'.
description
string
An optional description for the product.
active
boolean
Whether this product is active. Defaults to true.
images
string[]
An optional array of image URLs for the product.
features
{ name: string }[]
An optional list of features.
metadata
object
An optional set of key-value data.
prices
object[]
An optional array of price objects to create and attach to this product.
Example
async function createProduct() {
  try {
    const product = await payment.products.create({
      name: 'Monthly Subscription',
      description: 'Standard monthly access to our service.',
      type: 'service',
      prices: [{
        unit_amount: '1000', // e.g., $10.00
        currency_id: 'usd_123abc',
        type: 'recurring',
        recurring: {
          interval: 'month',
          interval_count: 1
        }
      }]
    });
    console.log('Product created:', product);
  } catch (error) {
    console.error('Error creating product:', error);
  }
}

createProduct();Example Response
{
  "id": "prod_1J2K3L4M5N6O7P8Q",
  "active": true,
  "livemode": false,
  "locked": false,
  "type": "service",
  "name": "Monthly Subscription",
  "description": "Standard monthly access to our service.",
  "images": [],
  "features": [],
  "unit_label": null,
  "default_price_id": null,
  "metadata": {},
  "statement_descriptor": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "prices": [
    {
      "id": "price_A1B2C3D4E5F6G7H8",
      "active": true,
      "type": "recurring",
      "unit_amount": "1000",
      "currency_id": "usd_123abc",
      "recurring": {
        "interval": "month",
        "interval_count": 1
      }
    }
  ]
}Retrieve a Product#Retrieves the details of an existing product.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the product to retrieve.
Example
async function retrieveProduct(productId) {
  try {
    const product = await payment.products.retrieve(productId);
    console.log('Retrieved product:', product);
  } catch (error) {
    console.error('Error retrieving product:', error);
  }
}

retrieveProduct('prod_1J2K3L4M5N6O7P8Q');Example Response
{
  "id": "prod_1J2K3L4M5N6O7P8Q",
  "active": true,
  "livemode": false,
  "locked": false,
  "type": "service",
  "name": "Monthly Subscription",
  "description": "Standard monthly access to our service.",
  "images": [],
  "features": [],
  "unit_label": null,
  "default_price_id": null,
  "metadata": {},
  "statement_descriptor": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Update a Product#Updates the specified product by setting the values of the parameters passed.
Parameters
Name
Type
Description
id
string
Required. The ID of the product to update.
updateData
object
Required. An object containing the fields to update.
Example
async function updateProduct(productId) {
  try {
    const updatedProduct = await payment.products.update(productId, {
      description: 'Upgraded: Standard monthly access with priority support.',
      metadata: { 'tier': 'standard' }
    });
    console.log('Product updated:', updatedProduct);
  } catch (error) {
    console.error('Error updating product:', error);
  }
}

updateProduct('prod_1J2K3L4M5N6O7P8Q');Example Response
{
  "id": "prod_1J2K3L4M5N6O7P8Q",
  "active": true,
  "description": "Upgraded: Standard monthly access with priority support.",
  "metadata": {
    "tier": "standard"
  },
  "updated_at": "2023-10-27T11:00:00.000Z"
}List all Products#Returns a paginated list of your products. The products are returned sorted by creation date, with the most recently created products appearing first.
Parameters
Name
Type
Description
active
boolean
Optional. Filter products by their active status.
name
string
Optional. Filter products by name (case-insensitive).
description
string
Optional. Filter products by description (case-insensitive).
metadata.{key}
string
Optional. Filter by a specific metadata key-value pair.
page
number
Optional. The page number to retrieve.
pageSize
number
Optional. The number of products to return per page. Defaults to 20.
order
string
Optional. The order to sort the results by. Example: created_at:DESC.
Example
async function listProducts() {
  try {
    const productList = await payment.products.list({
      active: true,
      pageSize: 5
    });
    console.log('Product List:', productList);
  } catch (error) {
    console.error('Error listing products:', error);
  }
}

listProducts();Example Response
{
  "count": 50,
  "list": [
    {
      "id": "prod_1J2K3L4M5N6O7P8Q",
      "name": "Monthly Subscription",
      "active": true
    },
    {
      "id": "prod_R9S8T7U6V5W4X3Y2",
      "name": "Annual Subscription",
      "active": true
    }
  ]
}Search Products#Searches for products that match a given query string.
Parameters
Name
Type
Description
query
string
Required. The search query string.
page
number
Optional. The page number to retrieve.
pageSize
number
Optional. The number of products to return per page. Defaults to 20.
Example
async function searchForProducts() {
  try {
    const results = await payment.products.search({ query: 'Subscription' });
    console.log('Search Results:', results);
  } catch (error) {
    console.error('Error searching products:', error);
  }
}

searchForProducts();Archive a Product#Archives a product, making it inactive and no longer available for new purchases. This is a reversible action.
Parameters
Name
Type
Description
id
string
Required. The ID of the product to archive.
Example
async function archiveProduct(productId) {
  try {
    const product = await payment.products.archive(productId);
    console.log('Product archived:', product.id, 'Active:', product.active);
  } catch (error) {
    console.error('Error archiving product:', error);
  }
}

archiveProduct('prod_1J2K3L4M5N6O7P8Q');Delete a Product#Permanently deletes a product. This action is irreversible.
Parameters
Name
Type
Description
id
string
Required. The ID of the product to delete.
Example
async function deleteProduct(productId) {
  try {
    const result = await payment.products.del(productId);
    console.log('Product deleted:', result.id);
  } catch (error) {
    console.error('Error deleting product:', error);
  }
}

deleteProduct('prod_1J2K3L4M5N6O7P8Q');

Attribute	Type	Description
`id`	`string`	Unique identifier for the product.
`active`	`boolean`	Whether the product is currently available for purchase.
`livemode`	`boolean`	`true` if the object exists in live mode, or `false` if it exists in test mode.
`locked`	`boolean`	Whether the product details can be modified. Defaults to `false`.
`type`	`string`	The product's type. Can be `service`, `good`, or `credit`.
`name`	`string`	The product's name, displayed to customers.
`description`	`string`	The product's description, displayed to customers.
`images`	`string[]`	A list of URLs for product images.
`features`	`object[]`	A list of features associated with the product. Each feature object has a `name` property.
`unit_label`	`string`	An optional label for a single unit of the product.
`default_price_id`	`string`	The ID of the default price for this product.
`metadata`	`object`	A set of key-value pairs for storing additional information.
`statement_descriptor`	`string`	An optional descriptor that appears on customer bank statements.
`created_at`	`Date`	The timestamp when the product was created.
`updated_at`	`Date`	The timestamp of the last update.

Name	Type	Description
`name`	`string`	Required. The product's name.
`type`	`string`	Required. The product type, such as `'service'` or `'good'`.
`description`	`string`	An optional description for the product.
`active`	`boolean`	Whether this product is active. Defaults to `true`.
`images`	`string[]`	An optional array of image URLs for the product.
`features`	`{ name: string }[]`	An optional list of features.
`metadata`	`object`	An optional set of key-value data.
`prices`	`object[]`	An optional array of price objects to create and attach to this product.

Name	Type	Description
`id`	`string`	Required. The ID of the product to update.
`updateData`	`object`	Required. An object containing the fields to update.

Name	Type	Description
`active`	`boolean`	Optional. Filter products by their active status.
`name`	`string`	Optional. Filter products by name (case-insensitive).
`description`	`string`	Optional. Filter products by description (case-insensitive).
`metadata.{key}`	`string`	Optional. Filter by a specific metadata key-value pair.
`page`	`number`	Optional. The page number to retrieve.
`pageSize`	`number`	Optional. The number of products to return per page. Defaults to `20`.
`order`	`string`	Optional. The order to sort the results by. Example: `created_at:DESC`.

Name	Type	Description
`query`	`string`	Required. The search query string.
`page`	`number`	Optional. The page number to retrieve.
`pageSize`	`number`	Optional. The number of products to return per page. Defaults to `20`.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Products

The Product Object#

Create a Product#

Retrieve a Product#

Update a Product#

List all Products#

Search Products#

Archive a Product#

Delete a Product#

Customers

Prices