Products & pricing

Products and prices are the catalog you charge against. A Product is the thing you sell ("Pro plan", "Widget"); a ProductPrice is the amount + cadence ("$10/month", "$0.10 per unit usage"). Subscriptions and checkouts both reference prices by ID.

Two namespaces:

client.products — the product catalog.
client.product_prices — prices attached to products.

`client.products`

`create`

product = client.products.create(
    name="Pro plan",
    description="Everything in Free, plus priority support.",
    metadata={"tier": "pro"},
    idempotency_key="product-pro-2025-01-01",
)

All fields are accepted via **kwargs. Returns: Product.

`update`

product = client.products.update("prod_123", description="…")

`retrieve`

product = client.products.retrieve("prod_123")

`list`

products = client.products.list(limit=50, offset=0)
batch    = client.products.list(ids=["prod_1", "prod_2"])

Returns list[Product].

`archive`

client.products.archive("prod_123")

Soft-deletes the product. Existing subscriptions on its prices keep running; you can no longer create new ones.

`with_prices`

bundle = client.products.with_prices("prod_123")
# bundle is a dict with the product + its prices joined

`with_price`

bundle = client.products.with_price("prod_123", "price_abc")

`client.product_prices`

`create`

# One-time price
one_time = client.product_prices.create(
    product_id="prod_123",
    currency="USD",
    unit_amount=2500,
    recurring=False,
    idempotency_key="price-onetime-prod_123",
)

# Recurring price
monthly = client.product_prices.create(
    product_id="prod_123",
    currency="USD",
    unit_amount=1000,
    recurring=True,
    interval="month",
    interval_count=1,
    idempotency_key="price-monthly-prod_123",
)

The discriminated union (recurring=True/False) is enforced server- side. Returns: ProductPrice.

`update`

price = client.product_prices.update("price_abc", metadata={"legacy": True})

`retrieve`

price = client.product_prices.retrieve("price_abc")

`list`

prices = client.product_prices.list(limit=50)

`archive`

client.product_prices.archive("price_abc")

Object shape

Product and ProductPrice follow the canonical shape from the API reference. EasyModel allows extras, so new fields appear on the model automatically.

Common fields:

Type	Field	Notes
`Product`	`id`, `name`, `description`, `active`, `metadata`
`ProductPrice`	`id`, `product_id`, `currency`, `unit_amount`	Integer cents.
`ProductPrice`	`recurring`, `interval`, `interval_count`	Recurring config.

Examples

Bootstrap a SaaS plan (product + monthly price)

product = client.products.create(name="Pro", description="Pro tier")
price = client.product_prices.create(
    product_id=product.id,
    currency="USD",
    unit_amount=2900,
    recurring=True,
    interval="month",
    interval_count=1,
)
print(price.id)

Rotate a price (archive old, create new)

client.product_prices.archive("price_old")
new_price = client.product_prices.create(
    product_id="prod_123",
    currency="USD",
    unit_amount=3500,
    recurring=True,
    interval="month",
    interval_count=1,
)

Render a product page

bundle = client.products.with_prices("prod_123")
print(bundle["name"])
for p in bundle.get("prices", []):
    print(p["id"], p["unit_amount"], p.get("interval"))

Products & pricing

On this page