Products

Product objects represent the goods, services, or digital credits you offer to your customers. You can think of them as the items in your catalog. Each product can have one or more associated prices.

This API allows you to create and manage your product catalog programmatically.

For details on managing the cost and billing schemes for these products, see the Prices API Reference.

The Product Object#

A Product object contains details about a single item you sell.

Attribute	Type	Description
id	string	Unique identifier for the product object.
name	string	The product's name, meant to be displayable to the customer.
type	string	The type of the product. Can be service, good, or credit. Defaults to service.
active	boolean	Whether the product is currently available for purchase.
description	string	An arbitrary string that you can use to describe the product.
images	string[]	A list of URL strings for images of the product.
metadata	object	A set of key-value pairs that you can attach to an object. Useful for storing additional information.
statement_descriptor	string	An optional descriptor that appears on your customer's credit card statement.
unit_label	string	A label that represents a single unit of this product (e.g., 'user', 'license').
nft_factory	string	The address of an NFT factory, if the product is linked to an NFT.
features	object[]	A list of features associated with the product. Each feature object has a name property.
prices	Price[]	A list of Price objects associated with this product. This is only included when retrieving a single product or in expanded lists.
default_price_id	string	The ID of the default price for this product.
created_at	string	Timestamp of when the object was created.
updated_at	string	Timestamp of the last update.

Create a Product#

Creates a new product object. You can also create one or more prices for the product at the same time.

const product = await payment.products.create({
  name: 'Premium Subscription',
  description: 'Monthly access to premium features.',
  type: 'service',
  prices: [
    {
      unit_amount: 1500, // e.g., 15.00 USD
      currency_id: 'usd_xxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
      },
    },
  ],
});

Parameters

Name	Type	Description
name	string	Required. The product's name.
type	string	The product type. One of service, good, or credit. Defaults to service.
description	string	An optional, user-facing description of the product.
images	string[]	A list of URLs for product images.
metadata	object	Key-value data to store with the product.
statement_descriptor	string	A short descriptor for credit card statements. Must contain at least one letter and cannot include <, >, ", ’, or \. Max 22 characters.
unit_label	string	A label for a single unit of the product (e.g., 'seat', 'GB'). Max 12 characters.
nft_factory	string	The address of an associated NFT factory contract.
features	object[]	A list of feature objects, where each object has a name property.
prices	object[]	An array of Price objects to create and attach to this product. See the Price Object Properties table below.

Price Object Properties

When creating a product, you can include an array of prices. Each object in the prices array can have the following properties:

Name	Type	Description
unit_amount	number	Required. The price in the smallest currency unit (e.g., cents for USD). Must be greater than 0.
currency_id	string	Required. The ID of the currency for this price.
nickname	string	An internal-facing name for the price.
type	string	one_time or recurring. Defaults to one_time.
recurring	object	Required if type is recurring. An object with an interval (day, week, month, or year) and optional interval_count.
custom_unit_amount	object	Defines a price where the customer can choose the amount. See the Prices API for details.

Returns

Returns the newly created Product object, including the list of any prices that were created.

{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "type": "service",
  "active": true,
  "description": "Monthly access to premium features.",
  "images": [],
  "metadata": {},
  "statement_descriptor": null,
  "unit_label": null,
  "nft_factory": null,
  "features": [],
  "default_price_id": "price_67890",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "prices": [
    {
      "id": "price_67890",
      "product_id": "prod_12345",
      "active": true,
      "type": "recurring",
      "unit_amount": "1500",
      "currency_id": "usd_xxxx",
      "recurring": {
        "interval": "month",

Retrieve a Product#

Retrieves the details of an existing product.

const product = await payment.products.retrieve('prod_12345');

Parameters

Name	Type	Description
id	string	Required. The unique identifier of the product to retrieve.

Returns

Returns a Product object if a valid ID was provided. Otherwise, this call returns an error.

{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "type": "service",
  "active": true,
  "description": "Monthly access to premium features.",
  // ... other product fields
  "prices": [
    // ... list of associated price objects
  ]
}

Update a Product#

Updates the specified product by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

const product = await payment.products.update('prod_12345', {
  description: 'Updated: Monthly access to all premium features and priority support.',
  metadata: { 'tier': 'premium' }
});

Parameters

Name	Type	Description
id	string	Required. The ID of the product to update.
name	string	The product's name.
description	string	An optional, user-facing description of the product.
images	string[]	A list of URLs for product images.
metadata	object	Key-value data to store with the product.
statement_descriptor	string	A short descriptor for credit card statements.
default_price_id	string	The ID of the price to set as the default for this product.
unit_label	string	A label for a single unit of the product.
features	object[]	A list of feature objects.

Returns

Returns the updated Product object.

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.

const products = await payment.products.list({
  active: true,
  limit: 10
});

Parameters

Name	Type	Description
active	boolean	Only return products with this active status.
name	string	Only return products with this name.
description	string	Only return products with this description.
type	string	Only return products of this type (e.g., credit).
metadata.{key}	string	Filter by a specific key-value pair in the metadata. For example, metadata.tier: 'premium'.
page	number	The page number to retrieve. Defaults to 1.
pageSize	number	The number of objects to return per page. Defaults to 20.

Returns

A paginated list of Product objects.

{
  "count": 50,
  "list": [
    {
      "id": "prod_12345",
      "name": "Premium Subscription",
      // ... other product fields
    },
    {
      "id": "prod_67890",
      "name": "Standard Plan",
      // ... other product fields
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}

Search Products#

Returns a list of products that match a search query.

const products = await payment.products.search({ query: 'Premium' });

Parameters

Name	Type	Description
query	string	The search query string. The search is performed on fields like name and description.
page	number	The page number to retrieve. Defaults to 1.
pageSize	number	The number of objects to return per page. Defaults to 20.

Returns

A paginated list of Product objects that match the search query.

Archive a Product#

Archives a product, making it unavailable for new purchases. This action toggles the active status of the product. Archiving a product will not affect existing subscriptions or purchases.

const product = await payment.products.archive('prod_12345');

Parameters

Name	Type	Description
id	string	Required. The ID of the product to archive.

Returns

Returns the updated Product object with its active status set to false (or true if it was already archived).

Delete a Product#

Permanently deletes a product. This action cannot be undone. A product can only be deleted if it has no prices or if none of its prices have been used in any transactions.

const deletedProduct = await payment.products.del('prod_12345');

Parameters

Name	Type	Description
id	string	Required. The ID of the product to delete.

Returns

Returns the deleted Product object.