Configuration File Format

Updated for v3.0.0

The Prices as Code configuration file is where you define your products and pricing structures. This guide explains the configuration format in detail and provides examples for both TypeScript and YAML formats.

Version 3.0.0 Updates

  • Simplified Provider Support: Now focuses exclusively on Stripe integration
  • Enhanced Sample Configurations: More comprehensive example files included
  • Improved Type Safety: Better TypeScript type definitions and validation

File Formats

Prices as Code supports both TypeScript/JavaScript and YAML configuration files:

Configuration Structure

TypeScript
YAML

Every configuration file has two main sections: products and prices:

// TypeScript example
import { Config } from 'prices-as-code';

const config: Config = {
  products: [
    // Product definitions
  ],
  prices: [
    // Price definitions
  ]
};

export default config;

Products Configuration

The products section defines your product offerings with the following properties:

Property Type Required Description
provider string Yes The payment provider (e.g., 'stripe')
name string Yes The product name
description string No A description of the product
features string[] No Array of feature descriptions for the product
highlight boolean No Whether to highlight this product in UI (e.g., as a recommended option)
metadata object No Custom metadata for the product
key string No Unique identifier for referencing this product (auto-generated if not provided)
id string No Provider-specific ID (populated after syncing)

Product Example

TypeScript
YAML
// TypeScript example
{
  provider: "stripe",
  name: "Pro Plan",
  description: "For growing businesses",
  features: [
    "Unlimited projects",
    "100GB storage",
    "Priority support",
    "Advanced analytics"
  ],
  highlight: true,
  metadata: {
    icon: "Star",
    color: "purple",
    displayOrder: 2,
  },
  key: "pro"
}

Prices Configuration

The prices section defines the pricing structure for your products with the following properties:

Property Type Required Description
provider string Yes The payment provider (e.g., 'stripe')
name string Yes The name of the price
nickname string No A shorter name for display purposes
unitAmount number Yes The amount in smallest currency units (e.g., cents for USD)
currency string Yes The three-letter currency code (e.g., 'usd', 'eur')
type string Yes Price type ('recurring' or 'one_time')
recurring object Conditionally Required if type is 'recurring'
productKey string Yes The key that links to a product
metadata object No Custom metadata for the price
key string No Unique identifier for this price (auto-generated if not provided)
id string No Provider-specific ID (populated after syncing)
active boolean No Whether the price is active (default: true)

Recurring Object Properties

Property Type Required Description
interval string Yes Billing interval ('day', 'week', 'month', or 'year')
intervalCount number No Number of intervals between billings (default: 1)

Price Example

TypeScript
YAML
// TypeScript example
{
  provider: "stripe",
  name: "Pro Monthly",
  nickname: "Pro Monthly",
  unitAmount: 1999, // $19.99
  currency: "usd",
  type: "recurring",
  recurring: {
    interval: "month",
    intervalCount: 1,
  },
  productKey: "pro",
  metadata: {
    plan_code: "pro_monthly",
    display_price: "$19.99",
  },
  active: true
}

Key Generation and Mapping

Prices as Code automatically generates keys for products and prices if they're not explicitly provided:

Metadata

Both products and prices support a metadata field for adding custom attributes. This is useful for:

Metadata is highly flexible and can contain any valid JSON data. Stripe limits metadata to strings, so PaC will convert non-string values automatically when syncing with Stripe.

Sample Configuration

Real-World Example

Here's a comprehensive example based on a tiered subscription model:

products:
  - name: Free
    description: Start your learning journey
    metadata:
      icon: Book
      color: blue
      key: free
    features:
      - Access to free content
      - Limited features
      - Core lessons
      - Ad-supported experience
    highlight: false
    provider: stripe
    key: free
    
  - name: Pro
    description: Help us shine bright with new features
    metadata:
      icon: Star
      color: purple
      key: pro
    features:
      - Support ongoing development
      - Supporter recognition
      - Early access to new features
      - Ad-free experience
      - Unlimited access
    highlight: true
    provider: stripe
    key: pro
    
  - name: Ultra
    description: The ultimate experience
    metadata:
      icon: Trophy
      color: amber
      key: ultra
    features:
      - All Pro perks
      - Ultra member recognition
      - Input on future features
      - Priority support
      - Personalized plans
    highlight: false
    provider: stripe
    key: ultra
    
prices:
  - name: Free
    unitAmount: 0
    currency: usd
    type: recurring
    recurring:
      interval: year
      intervalCount: 1
    active: true
    metadata:
      plan_code: free
      display_price: $0
    nickname: Free plan
    provider: stripe
    productKey: free
    
  - name: Pro Monthly
    unitAmount: 1000
    currency: usd
    type: recurring
    recurring:
      interval: month
      intervalCount: 1
    active: true
    metadata:
      plan_code: pro_monthly
      display_price: $10
    nickname: Pro Monthly Plan
    provider: stripe
    productKey: pro
    
  - name: Pro Yearly
    unitAmount: 9600
    currency: usd
    type: recurring
    recurring:
      interval: year
      intervalCount: 1
    active: true
    metadata:
      plan_code: pro_yearly
      display_price: $96
    nickname: Pro Yearly Plan
    provider: stripe
    productKey: pro

Next Steps