Prices API

Prices define the amount, currency, billing cadence, and trial settings for your products. Each product can have multiple prices for different plans or currencies.

GET/api/v1/payment/prices/

List all prices. Filter by product, is_active, price_type, lookup_key.

POST/api/v1/payment/prices/

Create a price. Body: { product_id, unit_amount, currency, price_type, pricing_mode?, billing_scheme?, recurring_interval?, trial_period_days?, tiers?, nickname?, description?, payment_method_required? }

GET/api/v1/payment/prices/{id}/

Get price detail.

PATCH/api/v1/payment/prices/{id}/

Update a price. Most fields are mutable.

DELETE/api/v1/payment/prices/{id}/

Archive a price (soft-delete).

POST/api/v1/payment/pricing-preview/

Preview localized pricing with tax. Body: { price_id, quantity?, country? }. Public endpoint (no auth required).

GET/api/v1/payment/pricing/localize/

Auto-detect currency from IP. Query: ?price_id=&country=. Public endpoint.

Price Object

{
  "id": "uuid",
  "product": "uuid",
  "product_name": "Pro Plan",
  "unit_amount": "29.99",
  "currency": "USD",
  "price_type": "recurring",    // one_time | recurring
  "pricing_mode": "standard",   // standard | pwyw | free
  "billing_scheme": "per_unit", // per_unit | tiered
  "recurring_interval": "month",
  "recurring_interval_count": 1,
  "recurring_usage_type": "licensed", // licensed | metered
  "trial_period_days": 14,
  "tiers": null,
  "tiers_mode": null,
  "is_active": true,
  "nickname": "Monthly Pro",
  "description": "Full access to all pro features",
  "payment_method_required": true,  // false = cardless trial
  "lookup_key": "pro_monthly",
  "metadata": {},
  "created_at": "2026-01-15T10:00:00Z"
}

Pricing Preview Response

// POST /api/v1/payment/pricing-preview/
// Body: { "price_id": "uuid", "quantity": 2, "country": "DE" }

{
  "price_id": "uuid",
  "product_id": "uuid",
  "quantity": 2,
  "country": "DE",
  "currency": "USD",
  "unit_amount": "29.99",
  "subtotal": "59.98",
  "tax_estimate": "11.40",
  "total": "71.38",
  "formatted_total": "USD 71.38",
  "price_name": "Monthly Pro",
  "price_description": "Full access to all pro features"
}