Products Pricing

Products and prices are the primitives behind subscriptions and recurring billing. A Product describes the thing being sold; a Price (a.k.a. product-price) describes how it's billed — currency, amount, billing interval, and tax behaviour.

The SDK splits these across two resources:

client.products — product CRUD plus nested-price reads.
client.product_prices — price CRUD.

Products

`client.products.list(limit: nil, offset: nil, ids: nil)`

GET /products.

client.products.list(limit: 25)

`client.products.retrieve(id)`

GET /products/:id.

`client.products.create(**body)`

POST /products.

product = client.products.create(name: "Pro plan", description: "Everything in Pro.")

`client.products.update(id, **body)`

PATCH /products/:id.

client.products.update("pr_…", name: "Pro plan v2")

`client.products.archive(id)`

PATCH /products/:id/archive.

client.products.archive("pr_…")

`client.products.with_prices(id)`

GET /products/:id/prices. Product object plus its full nested price list — handy for catalog rendering.

`client.products.with_price(id, price_id)`

GET /products/:id/prices/:price_id. Product plus a single price.

Product prices

`client.product_prices.list(limit: nil, offset: nil, ids: nil)`

GET /product-prices.

`client.product_prices.retrieve(id)`

GET /product-prices/:id.

`client.product_prices.create(**body)`

POST /product-prices. Body shape is a tagged union: pass either a recurring price or a one-off. The API enforces the discriminator.

client.product_prices.create(
  product_id:     "pr_…",
  active:         true,
  recurring:      true,
  currency:       "USD",
  unit_amount:    5_000,
  interval:       "month",
  interval_count: 1,
  tax_behavior:   "exclusive"
)

`client.product_prices.update(id, **body)`

PATCH /product-prices/:id.

client.product_prices.update("price_…", active: false)

`client.product_prices.archive(id)`

PATCH /product-prices/:id/archive.

Object shapes

Product — :id, :name, :description, :active, :metadata, :created_at, …

Price — :id, :product_id, :currency, :unit_amount, :recurring, :interval, :interval_count, :tax_behavior, :active, …

Examples

Create a product with a monthly price

product = client.products.create(name: "Pro plan")

price = client.product_prices.create(
  product_id:     product[:id],
  active:         true,
  recurring:      true,
  currency:       "USD",
  unit_amount:    4_900,
  interval:       "month",
  interval_count: 1,
  tax_behavior:   "exclusive"
)

client.subscriptions.create(
  identity_id:   customer[:id],
  items:         [{ price_id: price[:id] }],
  instrument_id: card[:id]
)

Render a catalog page

products = client.products.list(limit: 100)[:data] || []
catalog  = products.map { |p| client.products.with_prices(p[:id]) }

Products Pricing

On this page