Products & prices

A product represents what you sell; a price attaches an amount, currency, and billing behavior to it. Keeping them separate lets you change pricing — add a yearly plan, launch in a new currency, run a promotion — without ever touching the catalog item your customers recognize.

The product objectAskCopy

A product is the durable, customer-facing thing in your catalog: "Pro plan", "Seat license", "API access". It carries identity and metadata, not money. Products are shared across Payments and Billing, so the same prod_ works for a one-off charge and a subscription.

import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const product = await vinr.products.create({
  name: 'Pro plan',
  description: 'Everything in Starter, plus priority support.',
  active: true,
  metadata: { sku: 'PRO-2026', feature_tier: 'pro' },
});                                  // "prod_..."

The price objectAskCopy

A price binds money and cadence to a product. It is immutable in its core fields — amount, currency, and recurrence never change after creation. That immutability is deliberate: an invoice issued last month must always reflect the price it was billed at. To "change a price" you create a new one and migrate. See Versioning prices.

const monthly = await vinr.prices.create({
  product: product.id,             // "prod_..."
  amount: 2000,                    // €20.00 — integer minor units
  currency: 'EUR',
  recurring: { interval: 'month' },
  nickname: 'Pro / monthly EUR',   // internal label, never shown to customers
});                                // "price_..."

One-time vs. recurring pricesAskCopy

The presence of the recurring field is the only switch between the two kinds.

• One-time — no recurring block. Used for payment links, invoice items, and single charges (setup fees, hardware, credits).
• Recurring — set recurring.interval to day, week, month, or year. The price becomes attachable to a subscription, which generates an invoice each cycle.

// A €49.00 onboarding fee billed once.
const setupFee = await vinr.prices.create({
  product: product.id,
  amount: 4900,
  currency: 'EUR',
});

// €200.00 / year — interval_count lets you do "every 3 months", etc.
const yearly = await vinr.prices.create({
  product: product.id,
  amount: 20000,
  currency: 'EUR',
  recurring: { interval: 'year', interval_count: 1 },
});

// Bill by reported usage instead of a fixed quantity.
const metered = await vinr.prices.create({
  product: product.id,
  amount: 5,                       // €0.05 per unit
  currency: 'EUR',
  recurring: { interval: 'month', usage_type: 'metered' },
});

Multiple currenciesAskCopy

A single product can carry many prices, including the same plan in different currencies. Create one price per currency and let your checkout pick the one matching the customer's locale or country.

const prices = await Promise.all([
  vinr.prices.create({ product: product.id, amount: 2000, currency: 'EUR', recurring: { interval: 'month' } }),
  vinr.prices.create({ product: product.id, amount: 1800, currency: 'GBP', recurring: { interval: 'month' } }),
  vinr.prices.create({ product: product.id, amount: 2200, currency: 'USD', recurring: { interval: 'month' } }),
]);

Versioning pricesAskCopy

Because prices are immutable, raising the cost of "Pro / monthly EUR" means creating a new price and deciding what happens to existing subscribers. A common, low-friction pattern:

const priceV2 = await vinr.prices.create({
  product: product.id,
  amount: 2500,                    // €25.00 — the new rate
  currency: 'EUR',
  recurring: { interval: 'month' },
  nickname: 'Pro / monthly EUR (v2)',
});

await vinr.prices.update(oldPrice.id, { active: false });

Next stepsAskCopy