Skip to main content

​
Customers

A customer represents an end user or account in your system.
  • It is not a Stripe customer
  • It is not a subscription
  • It is an identity you control
In the PriceOS API, customers are referenced using an identifier you already have: 
externalCustomerId: "cus_123"
PriceOS links this customer to one or more Stripe subscriptions under the hood, but your app never needs to care how that linkage works.

​
Prices

A price represents something a customer is billed for. In Stripe terms, this maps directly to a Stripe Price (price_...). In PriceOS:
  • A customer can have one or more prices
  • Each price may have a quantity (for add-ons like seats)
  • Prices are the only billing-aware objects
PriceOS never calculates money — it only records what a customer is paying for.

​
Products

A product represents a bundle of functionality. Think of a product as:
“A specific version of a plan”
Examples:
  • Starter v1
  • Pro v3
  • Enterprise v2
Products are versioned so you can:
  • Change features for new customers
  • Keep existing customers on their original terms

​
Product Versions

A product version is immutable. Once created:
  • Its feature access never changes
  • Existing customers are permanently tied to it
When you need to change something:
  • You create a new product version
  • New customers link to the new version
  • Existing customers stay where they are
This is the mechanism that prevents accidental access regressions.

​
Feature Access

Feature access defines what a product version allows a customer to do. There are two supported types:

​
Boolean features

Used for on/off capabilities. Examples:
  • AI Images enabled
  • API access
  • Export functionality
{
  "ai_images": true
}

​
Limit-based features

Used for counts, seats, or quotas. Examples:
  • Team members
  • Monthly usage limits
  • Credits
{
  "team_members": 7
}
Limits can come from:
  • Multiple products
  • Quantities on prices
PriceOS automatically merges them into a single result.

​
How access is calculated

At runtime, PriceOS follows a deterministic process:
  1. Identify the customer
  2. Load the prices they are subscribed to
  3. Resolve those prices to product versions
  4. Aggregate feature access across products
Your application receives a single, final answer. No branching. No Stripe conditionals.

​
Mental model summary

You can think of PriceOS like this: 
Stripe Prices
      ↓
PriceOS Products (versioned)
      ↓
Feature Access
      ↓
Your application logic
Each layer has a single responsibility.

​
What’s next

Now that you understand the core concepts, you can: