API Reference

Products

Product objects represent the goods, services, or credits you offer. You can use products to model your offerings and manage them within the PaymentKit system. Each product can have one or more associated prices.
For more details on managing pricing, see the Prices API documentation.
The Product Object#A TProductExpanded object contains detailed information about a product, including its associated prices.
Attribute
Type
Description
id
string
Unique identifier for the product object.
name
string
The product's name, meant to be displayable to the customer.
description
string
The product's description, meant to be displayable to the customer.
active
boolean
Whether the product is currently available for purchase.
type
string
The type of product. Can be service, good, or credit. Defaults to service.
images
string[]
A list of URLs of images for this product, meant to be displayable to the customer.
metadata
object
A set of key-value pairs that you can attach to an object. Useful for storing additional information.
unit_label
string
A label that represents a single unit of this product.
statement_descriptor
string
An arbitrary string to be displayed on your customer's credit card statement.
features
object[]
A list of features associated with the product. Each object has a name property.
default_price_id
string
The ID of the default price for this product.
prices
TPrice[]
An array of Price objects associated with 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.
Parameters
Name
Type
Description
name
string
Required. The product's name. Maximum 64 characters.
type
string
The type of product. Can be service, good, or credit. Defaults to service.
description
string
An optional description of the product. Maximum 250 characters.
prices
object[]
An optional array of price objects to create and attach to this product. See details below.
metadata
object
A set of key-value pairs for storing additional information.
images
string[]
An optional list of image URLs for the product.
statement_descriptor
string
A statement descriptor. Must be at least one letter and cannot include Chinese characters or <>"'\\. Maximum 22 characters.
unit_label
string
A label for a single unit of the product. Maximum 12 characters.
features
object[]
A list of feature objects, each with a name property.
nft_factory
string
The associated NFT factory address. Maximum 40 characters.
prices Object Properties
Name
Type
Description
unit_amount
number
Required unless custom_unit_amount is provided. The price in the smallest currency unit (e.g., cents for USD). Must be greater than 0.
custom_unit_amount
object
Required unless unit_amount is provided. Defines a price with a customer-selectable amount.
currency_id
string
The ID of the currency for this price. If not provided, the blocklet's default currency is used.
nickname
string
An internal-facing name for the price. Maximum 64 characters.
currency_options
object[]
An array to define prices for this item in multiple currencies. Each object contains currency_id and unit_amount.
lookup_key
string
A unique string that you can use to look up a price. Maximum 64 characters.
metadata
object
A set of key-value pairs for the price. Required for credit type products. See credit_config below.
metadata.credit_config Object Properties (Required for credit type products)
Name
Type
Description
credit_amount
number
Required. The amount of credit this price grants. Must be greater than 0.
currency_id
string
Required. The ID of the credit currency.
valid_duration_value
number
The duration for which the granted credit is valid. Defaults to 0 (indefinite).
valid_duration_unit
string
The unit for valid_duration_value. Can be hours, days, weeks, months, years. Defaults to days.
priority
number
The priority of this credit, from 0 to 100. Higher values are consumed first. Defaults to 50.
applicable_prices
string[]
An array of price IDs that this credit can be applied to. Defaults to an empty array (applicable to all).
Example#const newProduct = await payment.products.create({
  name: 'Premium Subscription',
  type: 'service',
  description: 'Monthly access to premium features.',
  prices: [
    {
      unit_amount: 2999, // e.g., $29.99
      currency_id: 'usd_xxxx',
      recurring: {
        interval: 'month'
      }
    }
  ]
});

console.log(newProduct);Example Response#{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "type": "service",
  "description": "Monthly access to premium features.",
  "active": true,
  "livemode": false,
  "metadata": {},
  "prices": [
    {
      "id": "price_67890",
      "product_id": "prod_12345",
      "unit_amount": "2999",
      "currency_id": "usd_xxxx",
      "type": "recurring",
      "recurring": {
        "interval": "month",
        "interval_count": 1
      },
      "active": true
    }
  ],
  "default_price_id": "price_67890"
}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#const productId = 'prod_12345';
const product = await payment.products.retrieve(productId);

console.log(product);Example Response#{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "description": "Monthly access to premium features.",
  "active": true,
  "prices": []
}Update a Product#Updates the specified product by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Parameters
Name
Type
Description
id
string
Required. The ID of the product to update.
name
string
The product's new name.
description
string
The product's new description.
images
string[]
A list of image URLs.
metadata
object
A set of key-value pairs to update.
statement_descriptor
string
The new statement descriptor.
default_price_id
string
The ID of the new default price.
unit_label
string
The new unit label.
features
object[]
The new list of features.
nft_factory
string
The new NFT factory address.
Example#const productId = 'prod_12345';
const updatedProduct = await payment.products.update(productId, {
  description: 'Updated monthly access description.'
});

console.log(updatedProduct);Example Response#{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "description": "Updated monthly access description.",
  "active": true,
  "prices": []
}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
page
number
The page number for pagination, starting from 1. Defaults to 1.
pageSize
number
The number of objects to return per page. Defaults to 20.
active
boolean
Optional. Set to true to only return active products, or false to return inactive products.
name
string
Optional. Filter products by name.
description
string
Optional. Filter products by description.
type
string
Optional. Filter products by type (e.g., credit, service, good).
metadata.{key}
string
Optional. Filter by a specific metadata key-value pair. e.g., metadata.internal_id: 'xyz'.
Example#const productList = await payment.products.list({ 
  active: true,
  pageSize: 5 
});

console.log(productList);Example Response#{
  "count": 50,
  "list": [
    {
      "id": "prod_abcde",
      "name": "Another Product",
      "active": true
    },
    {
      "id": "prod_12345",
      "name": "Premium Subscription",
      "active": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}Search Products#Searches for products that match a query string. This is useful for implementing product search functionality in your application.
Parameters
Name
Type
Description
query
string
Required. The search query string. The API will search for this string in product names and descriptions.
page
number
The page number for pagination. Defaults to 1.
pageSize
number
The number of objects to return per page. Defaults to 20.
Example#const searchResults = await payment.products.search({ 
  query: 'Premium',
  pageSize: 10
});

console.log(searchResults);Example Response#{
  "count": 1,
  "list": [
    {
      "id": "prod_12345",
      "name": "Premium Subscription",
      "description": "Monthly access to premium features.",
      "active": true
    }
  ]
}Archive a Product#Archives a product, making it inactive. Archived products can no longer be used in new transactions but are kept for historical purposes. This action toggles the product's active status.
Parameters
Name
Type
Description
id
string
Required. The ID of the product to archive.
Example#const productId = 'prod_12345';
const archivedProduct = await payment.products.archive(productId);

console.log(archivedProduct.active); // falseExample Response#{
  "id": "prod_12345",
  "name": "Premium Subscription",
  "active": false
}Delete a Product#Permanently deletes a product. It 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.
Parameters
Name
Type
Description
id
string
Required. The ID of the product to delete.
Example#const productId = 'prod_to_delete';
const deletedProduct = await payment.products.del(productId);

console.log(deletedProduct);Example Response#{
  "id": "prod_to_delete",
  "name": "Temporary Product"
}This operation permanently removes the product and its associated prices and cannot be undone.

Attribute	Type	Description
`id`	`string`	Unique identifier for the product object.
`name`	`string`	The product's name, meant to be displayable to the customer.
`description`	`string`	The product's description, meant to be displayable to the customer.
`active`	`boolean`	Whether the product is currently available for purchase.
`type`	`string`	The type of product. Can be `service`, `good`, or `credit`. Defaults to `service`.
`images`	`string[]`	A list of URLs of images for this product, meant to be displayable to the customer.
`metadata`	`object`	A set of key-value pairs that you can attach to an object. Useful for storing additional information.
`unit_label`	`string`	A label that represents a single unit of this product.
`statement_descriptor`	`string`	An arbitrary string to be displayed on your customer's credit card statement.
`features`	`object[]`	A list of features associated with the product. Each object has a `name` property.
`default_price_id`	`string`	The ID of the default price for this product.
`prices`	`TPrice[]`	An array of Price objects associated with this product.
`created_at`	`string`	Timestamp of when the object was created.
`updated_at`	`string`	Timestamp of the last update.

Name	Type	Description
`name`	`string`	Required. The product's name. Maximum 64 characters.
`type`	`string`	The type of product. Can be `service`, `good`, or `credit`. Defaults to `service`.
`description`	`string`	An optional description of the product. Maximum 250 characters.
`prices`	`object[]`	An optional array of price objects to create and attach to this product. See details below.
`metadata`	`object`	A set of key-value pairs for storing additional information.
`images`	`string[]`	An optional list of image URLs for the product.
`statement_descriptor`	`string`	A statement descriptor. Must be at least one letter and cannot include Chinese characters or `<>"'\\`. Maximum 22 characters.
`unit_label`	`string`	A label for a single unit of the product. Maximum 12 characters.
`features`	`object[]`	A list of feature objects, each with a `name` property.
`nft_factory`	`string`	The associated NFT factory address. Maximum 40 characters.

Name	Type	Description
`unit_amount`	`number`	Required unless `custom_unit_amount` is provided. The price in the smallest currency unit (e.g., cents for USD). Must be greater than 0.
`custom_unit_amount`	`object`	Required unless `unit_amount` is provided. Defines a price with a customer-selectable amount.
`currency_id`	`string`	The ID of the currency for this price. If not provided, the blocklet's default currency is used.
`nickname`	`string`	An internal-facing name for the price. Maximum 64 characters.
`currency_options`	`object[]`	An array to define prices for this item in multiple currencies. Each object contains `currency_id` and `unit_amount`.
`lookup_key`	`string`	A unique string that you can use to look up a price. Maximum 64 characters.
`metadata`	`object`	A set of key-value pairs for the price. Required for `credit` type products. See `credit_config` below.

Name	Type	Description
`credit_amount`	`number`	Required. The amount of credit this price grants. Must be greater than 0.
`currency_id`	`string`	Required. The ID of the credit currency.
`valid_duration_value`	`number`	The duration for which the granted credit is valid. Defaults to `0` (indefinite).
`valid_duration_unit`	`string`	The unit for `valid_duration_value`. Can be `hours`, `days`, `weeks`, `months`, `years`. Defaults to `days`.
`priority`	`number`	The priority of this credit, from 0 to 100. Higher values are consumed first. Defaults to `50`.
`applicable_prices`	`string[]`	An array of price IDs that this credit can be applied to. Defaults to an empty array (applicable to all).

Name	Type	Description
`id`	`string`	Required. The ID of the product to update.
`name`	`string`	The product's new name.
`description`	`string`	The product's new description.
`images`	`string[]`	A list of image URLs.
`metadata`	`object`	A set of key-value pairs to update.
`statement_descriptor`	`string`	The new statement descriptor.
`default_price_id`	`string`	The ID of the new default price.
`unit_label`	`string`	The new unit label.
`features`	`object[]`	The new list of features.
`nft_factory`	`string`	The new NFT factory address.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Products

The Product Object#

Create a Product#

Example#

Example Response#

Retrieve a Product#

Example#

Example Response#

Update a Product#

Example#

Example Response#

List all Products#

Example#

Example Response#

Search Products#

Example#

Example Response#

Archive a Product#

Example#

Example Response#

Delete a Product#

Example#

Example Response#

Customers

Prices

Name	Type	Description
`page`	`number`	The page number for pagination, starting from 1. Defaults to 1.
`pageSize`	`number`	The number of objects to return per page. Defaults to 20.
`active`	`boolean`	Optional. Set to `true` to only return active products, or `false` to return inactive products.
`name`	`string`	Optional. Filter products by name.
`description`	`string`	Optional. Filter products by description.
`type`	`string`	Optional. Filter products by type (e.g., `credit`, `service`, `good`).
`metadata.{key}`	`string`	Optional. Filter by a specific metadata key-value pair. e.g., `metadata.internal_id: 'xyz'`.

Name	Type	Description
`query`	`string`	Required. The search query string. The API will search for this string in product names and descriptions.
`page`	`number`	The page number for pagination. Defaults to 1.
`pageSize`	`number`	The number of objects to return per page. Defaults to 20.