Sign in

v1

latestOpenAPI 3.0.32026-07-264469137.7 KB
Products

Create a product

Creates a product with its pricing. Every product has a price; add a billing_cycle to make it recurring, or omit it for a one-time product. Sell products through checkout sessions and subscriptions. Requires the products:write scope.

post/v1/products

Request body

namestring required

Display name of the product. Shown to customers at checkout.

descriptionstring nullable

Optional description of the product. Shown to customers at checkout.

metadataobject nullable

Up to 20 key/value pairs for your own reference.

Example request

{
  "name": "Pro Plan",
  "description": "Monthly access to all Pro features.",
  "price": {
    "currency": "USD",
    "price_type": "fixed",
    "amount": "29.00",
    "preset_amount": "15.00",
    "minimum_amount": "5.00",
    "maximum_amount": "500.00",
    "currency_options": [
      {
        "currency": "NGN",
        "amount": "45000.00"
      }
    ]
  },
  "metadata": {
    "order_id": "ORD-9876",
    "tier": "pro"
  },
  "billing_cycle": {
    "interval": "month",
    "frequency": 1
  },
  "trial_period": {
    "interval": "day",
    "frequency": 14
  }
}

Response

Product created

idstring

Unique identifier for the product, prefixed with prod_.

organization_idstring

The organization that owns the product.

namestring

Display name of the product.

descriptionstring nullable

Optional description of the product. null when not set.

status'active' | 'archived'

Status of the product. active: Live and available for use in checkouts and subscriptions. archived: Retired. Kept for reference but not available for new purchases.

metadataobject nullable

Your own key-value data attached to the product, returned unchanged.

actor_idstring

Identifier of the user or key that created the product.

created_atstring date-time

ISO 8601 timestamp when the product was created.

updated_atstring date-time

ISO 8601 timestamp when the product was last updated.

archived_atstring date-time nullable

When set, the product is archived and cannot be used in new checkouts. null while the product is active.

pricesobject[]

All prices configured on the product, one per currency. Each has currency, amount, optional minimum_amount and maximum_amount, and is_default.

total_paymentsinteger

Running count of completed payments for this product. Starts at 0 and increments as customers pay.

total_amountstring

Running total collected for this product, as a decimal string in the product currency. Starts at "0.00".

Example response

{
  "id": "prod_1a2b3c4d5e6f",
  "organization_id": "org_abc123",
  "name": "Pro Plan",
  "description": "Monthly access to all Pro features.",
  "price": {
    "currency": "USD",
    "price_type": "fixed",
    "amount": "29.00",
    "preset_amount": "15.00",
    "minimum_amount": "5.00",
    "maximum_amount": "500.00",
    "currency_options": [
      {
        "currency": "GHS",
        "amount": "35.00",
        "minimum_amount": "5.00",
        "maximum_amount": "500.00"
      }
    ]
  },
  "status": "active",
  "metadata": {
    "order_id": "ORD-9876",
    "tier": "pro"
  },
  "actor_id": "usr_abc123",
  "created_at": "2026-07-13T14:00:00.000Z",
  "updated_at": "2026-07-13T14:00:00.000Z",
  "billing_cycle": {
    "interval": "month",
    "frequency": 1
  },
  "trial_period": {
    "interval": "day",
    "frequency": 14
  },
  "total_amount": "0.00"
}