Prices
Flexible pricing models - one-time, recurring, and pay-what-you-want
Prices define how much a product costs and how it's billed. A single product can have multiple prices, enabling flexible pricing strategies like offering both monthly and annual billing options.
Price Types
One-Time Price
A single payment for a product. Perfect for physical goods, digital downloads, or services with a fixed scope.
Example: Software license for $299
Recurring Price
Repeated billing at a specified interval. Used for subscriptions, memberships, and ongoing services.
Billing intervals:
- Daily, Weekly, Monthly, Yearly
- Custom intervals (e.g., every 3 months, every 6 weeks)
Pay-What-You-Want
Let customers choose their own price. You can set minimum and suggested amounts. Great for donations, tips, or flexible pricing experiments.
Example: Minimum $5, suggested $25
Price Fields
| Field | Type | Description |
|---|---|---|
amount_minor | integer | Price in minor units (cents). $29.99 = 2999 |
currency | string | ISO currency code (USD, EUR, GBP, etc.) |
type | enum | one_time, recurring, or pay_what_you_want |
billing_interval | enum | day, week, month, year (recurring only) |
billing_interval_count | integer | Number of intervals between charges (default: 1) |
trial_period_days | integer | Free trial duration in days (recurring only) |
is_active | boolean | Whether price is available for new purchases |
Creating Prices
One-Time Price
const price = await client.prices.create({
productId: 'prod_xxxxxxxx',
amountMinor: 29900, // $299.00
currency: 'USD',
type: 'one_time',
});
console.log(price.data.id); // price_xxxxxxxxMonthly Subscription
const monthlyPrice = await client.prices.create({
productId: 'prod_xxxxxxxx',
amountMinor: 2900, // $29.00/month
currency: 'USD',
type: 'recurring',
billingInterval: 'month',
billingIntervalCount: 1,
trialPeriodDays: 14, // 14-day free trial
});Annual Subscription (with discount)
// Annual price with 2 months free (10 months = $290 instead of $348)
const annualPrice = await client.prices.create({
productId: 'prod_xxxxxxxx',
amountMinor: 29000, // $290.00/year
currency: 'USD',
type: 'recurring',
billingInterval: 'year',
billingIntervalCount: 1,
});Quarterly Billing (Custom Interval)
// Bill every 3 months
const quarterlyPrice = await client.prices.create({
productId: 'prod_xxxxxxxx',
amountMinor: 7500, // $75.00 every 3 months
currency: 'USD',
type: 'recurring',
billingInterval: 'month',
billingIntervalCount: 3, // Every 3 months
});Trial Periods
For recurring prices, you can offer a free trial period. During the trial:
- Customer gets full access to the product
- No payment is collected
- Subscription status is
trialing - At trial end, the first invoice is generated and charged
Multiple Prices per Product
A single product can have multiple prices. Common patterns include:
| Pattern | Example | Benefit |
|---|---|---|
| Monthly + Annual | $29/mo or $290/yr | Capture both preference types |
| Multiple tiers | Basic $19, Pro $49, Enterprise $199 | Different feature levels |
| Multi-currency | $29 USD, €27 EUR, £24 GBP | Localized pricing |
| One-time + Recurring | $99 setup + $29/mo | Setup fee with subscription |
Best Practices
Annual plans with a discount (typically 15-20% off) improve cash flow and reduce churn
7-14 day trials work best for most SaaS products
Always use cents/minor units to avoid floating point issues ($29.99 = 2999)
Set is_active: false instead of deleting prices to preserve history