Core concepts

PaymentKit’s product catalog is built on two main entities:

Entity	Description
Products	The items or services you sell, each with a name, description, and unit label.
Prices	How and when you charge for a product, including amount, currency, and billing behavior.

Products

A product represents something you sell. Each product can have multiple prices for different billing models, currencies, or tiers.

Key product fields:

Field	Description
Name	Display name shown to customers
Description	Optional details about the product that will appear in checkout/customer billing portal sessions

Prices

Prices define how much to charge for a product. A single product can have multiple prices for different scenarios.

Key price fields:

Field	Description
Pricing model	When customers are charged (flat or usage-based)
Pricing structure	How the price scales (fixed, tiered, or package)
Amount	The price in minor units (cents for USD)
Currency	ISO 4217 currency code (e.g., “usd”, “eur”)
Billing period	How often recurring charges occur (monthly, yearly)

Pricing models

A pricing model defines how and when customers are charged for a product. PaymentKit supports the following pricing models:

Flat

Charge a fixed amount regardless of quantity or usage—works for both one-time and recurring billing (e.g., $29/month).

Usage-based

Metered, measured, billed after usage—charge is based on actual consumption over time (e.g., $0.01 per API call).

Pricing structures

A pricing structure defines how the unit price changes as quantity or usage increases. PaymentKit supports the following pricing structures:

Fixed

Charge a fixed price for each unit of a product or service, regardless of quantity.

Tiered

Charge different prices based on quantity thresholds using graduated or volume tiers.

Package

Charge a fixed price for a predefined bundle of units, rather than pricing each unit individually.

Example: SaaS product catalog

A typical SaaS product catalog might look like:

Products:
├── Pro Plan (flat)
│   ├── Price: $29/month
│   └── Price: $290/year
├── Enterprise Plan (flat)
│   ├── Price: $99/month
│   └── Price: $990/year
├── Additional Seats (flat, fixed structure)
│   └── Price: $10/seat/month
└── Storage Add-on (usage-based, tiered structure)
    └── Price: $0.10/GB/month

Packages, discounts, and upgrade paths

Packages

Present multiple related products together at checkout and let customers select the option that fits their needs.

Discounts

Apply discounts to products or prices using configurable percentage or fixed-amount rules.

Upgrade paths

Control how customers can move between products by defining allowed upgrade and downgrade paths.