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.

Create a Product

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

Create Product

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',
        interval_count: 1,
        usage_type: 'licensed'
      },
    },
  ],
});

Parameters

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:

Returns

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

Response Example

{
  "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",
        "interval_count": 1
      }
    }
  ]
}

Retrieve a Product

Retrieves the details of an existing product.

Retrieve Product

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

Parameters

Returns

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

Response Example

{
  "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.

Update Product

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

Parameters

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.

List Products

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

Parameters

Returns

A paginated list of Product objects.

Response Example

{
  "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.

Search Products

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

Parameters

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.

Archive Product

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

Parameters

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.

Delete Product

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

Parameters

Returns

Returns the deleted Product object.