Stripe Integration Overview
Learn how OmniBase handles billing, subscriptions, and payment processing with Stripe
Stripe Integration
OmniBase provides a comprehensive "Stripe as Code" approach to billing configuration, enabling version control, rollbacks, audit trails, and enterprise-grade payment processing.
Key Features
Configuration as Code
Version-controlled billing configuration with JSON/YAML
Products & Prices
Define products with multiple pricing tiers and intervals
Coupons & Promotions
Create discount codes and promotional campaigns
Webhooks
Configure webhook endpoints for event handling
Subscriptions
Manage recurring billing and subscription lifecycle
Usage-Based Billing
Implement metered billing with billing meters
Checkout & Portal
Integrate Stripe Checkout and Customer Portal
Invoices
Create and manage invoices programmatically
Enterprise Pricing
Custom pricing templates for enterprise customers
UI Components
Pre-built shadcn components for pricing tables and billing UI
The Problem with Native Stripe
Stripe's configuration presents several challenges for production systems:
| Challenge | Description |
|---|---|
| Immutability | Products and prices with payment history cannot be deleted |
| No Version Control | No built-in rollback or history tracking |
| Environment Sync | Difficult to sync configurations between dev/staging/prod |
| Free Tiers | Stripe doesn't natively support $0 prices |
| Enterprise Pricing | No built-in support for custom per-customer pricing |
OmniBase Solution
OmniBase stores your Stripe configuration in PostgreSQL and syncs it to Stripe, providing:
- Version Control — Every configuration change is tracked with full history
- Rollbacks — Revert to any previous configuration instantly
- Audit Trails — Complete history of all billing changes with timestamps
- Free Tiers — Support $0 pricing stored locally (bypasses Stripe's limitation)
- Config ID Mapping — Human-readable IDs (
pro_monthly) mapped to Stripe IDs (price_1ABC...) - Enterprise Pricing — Template-based and custom per-tenant pricing
Quick Start
Create Your Configuration
Create a configuration file in your project:
{
"$schema": "https://dashboard.omnibase.tech/api/stripe-config.schema.json",
"version": "1.0.0",
"products": [
{
"id": "starter",
"name": "Starter Plan",
"description": "Perfect for individuals",
"type": "service",
"prices": [
{
"id": "starter_monthly",
"amount": 0,
"currency": "usd",
"interval": "month",
"public": true,
"ui": {
"display_name": "Free",
"price_display": { "custom_text": "Free" }
}
}
]
},
{
"id": "pro",
"name": "Professional",
"description": "For growing businesses",
"type": "service",
"prices": [
{
"id": "pro_monthly",
"amount": 4900,
"currency": "usd",
"interval": "month",
"public": true,
"default": true
},
{
"id": "pro_yearly",
"amount": 49000,
"currency": "usd",
"interval": "year",
"public": true
}
],
"ui": {
"highlighted": true,
"badge": "Most Popular"
}
}
]
}Push to Stripe
Use the CLI to validate and push your configuration:
# Validate configuration without pushing
omnibase stripe validate
# Push configuration to Stripe
omnibase stripe pushThis will:
- Validate your configuration against the JSON schema
- Create/update products and prices in Stripe
- Store the configuration version in PostgreSQL
- Generate config ID to Stripe ID mappings
Use in Your Application
Fetch the configuration and create checkouts:
import { V1StripeApi, V1PaymentsApi } from '@omnibase/core-js';
export default async function SubscriptionsPage() {
const stripeApi = new V1StripeApi(config);
const paymentsApi = new V1PaymentsApi(config);
// Get available plans
const { data: stripeConfig } = await stripeApi.getStripeConfig();
async function checkout(priceId: string) {
'use server';
const { data } = await paymentsApi.createCheckout({
createCheckoutRequest: {
priceId,
successUrl: `${process.env.APP_URL}/subscriptions?success=true`,
cancelUrl: `${process.env.APP_URL}/subscriptions`,
trialPeriodDays: 14,
allowPromotionCodes: true,
},
});
redirect(data.url);
}
return <PricingTable products={stripeConfig.products} onSelect={checkout} />;
}import { useEffect, useState } from 'react';
import { V1StripeApi, V1PaymentsApi, Product } from '@omnibase/core-js';
export function Pricing() {
const [products, setProducts] = useState<Product[]>([]);
useEffect(() => {
const stripeApi = new V1StripeApi(config);
stripeApi.getStripeConfig().then(({ data }) => {
setProducts(data.products);
});
}, []);
const handleCheckout = async (priceId: string) => {
const paymentsApi = new V1PaymentsApi(config);
const { data } = await paymentsApi.createCheckout({
createCheckoutRequest: {
priceId,
successUrl: `${window.location.origin}/success`,
cancelUrl: window.location.href,
},
});
window.location.href = data.url;
};
return <PricingTable products={products} onSelect={handleCheckout} />;
}import { Configuration, V1StripeApi, V1PaymentsApi } from '@omnibase/core-js';
const config = new Configuration({
basePath: process.env.OMNIBASE_API_URL,
headers: { Cookie: cookieHeader },
});
// Get configuration
const stripeApi = new V1StripeApi(config);
const { data: stripeConfig } = await stripeApi.getStripeConfig();
// Create checkout session
const paymentsApi = new V1PaymentsApi(config);
const { data: checkout } = await paymentsApi.createCheckout({
createCheckoutRequest: {
priceId: 'pro_monthly',
successUrl: 'https://example.com/success',
cancelUrl: 'https://example.com/pricing',
},
});
console.log('Checkout URL:', checkout.url);Architecture Overview
┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐
│ Config Files │────▶│ OmniBase API │────▶│ Stripe │
│ (JSON/YAML) │ │ (PostgreSQL) │ │ (Live) │
└─────────────────┘ └──────────────────┘ └─────────────┘
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ ID Mappings │ │
│ │ config_id ↔ │◀───────────┘
│ │ stripe_id │
│ └──────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ Version │ │ Change │
│ History │ │ Detection │
└─────────────────┘ └──────────────────┘Key Components:
- Configuration Files — JSON files defining products, prices, meters, webhooks, coupons
- PostgreSQL Storage — Versioned configuration with full history
- ID Mapping — Bi-directional mapping between config IDs and Stripe IDs
- Stripe Sync — Intelligent diffing and synchronization to Stripe API
Configuration File Structure
OmniBase supports multiple configuration files for better organization:
Each file follows the same schema with optional sections:
{
"$schema": "https://dashboard.omnibase.tech/api/stripe-config.schema.json",
"version": "1.0.0",
"webhooks": [], // Optional: Webhook endpoints
"meters": [], // Optional: Billing meters for metered pricing
"products": [], // Required: At least one product
"coupons": [], // Optional: Discount coupons
"promotion_codes": [] // Optional: Promotion codes for coupons
}Supported Currencies
OmniBase supports 20 currencies:
| Currency | Code | Currency | Code |
|---|---|---|---|
| US Dollar | usd | Euro | eur |
| British Pound | gbp | Canadian Dollar | cad |
| Australian Dollar | aud | Japanese Yen | jpy |
| Indian Rupee | inr | Brazilian Real | brl |
| Mexican Peso | mxn | Singapore Dollar | sgd |
| Hong Kong Dollar | hkd | New Zealand Dollar | nzd |
| Swiss Franc | chf | Swedish Krona | sek |
| Danish Krone | dkk | Norwegian Krone | nok |
| Polish Zloty | pln | Czech Koruna | czk |
| Israeli Shekel | ils | South African Rand | zar |
CLI Commands
| Command | Description |
|---|---|
omnibase stripe push | Push local configuration to Stripe |
omnibase stripe pull | Pull configuration from Stripe account |
omnibase stripe validate | Validate configuration without pushing |
omnibase stripe history | View configuration version history |
omnibase stripe webhook secret | Retrieve webhook signing secrets |
API Endpoints
Public Endpoints (No Auth Required)
| Endpoint | Description |
|---|---|
GET /api/v1/stripe/schema | Get JSON schema for configuration |
GET /api/v1/stripe/config | Get public configuration (filtered) |
GET /api/v1/stripe/config/prices/:id | Get price by config ID |
GET /api/v1/stripe/config/products/:id | Get product by config ID |
GET /api/v1/stripe/config/meters/:id | Get meter by config ID |
POST /api/v1/stripe/config/prices/:id/calculate | Calculate cost for quantity |
Admin Endpoints (Service Key Required)
| Endpoint | Description |
|---|---|
GET /api/v1/stripe/admin/config | Get full configuration (unfiltered) |
POST /api/v1/stripe/admin/config | Update configuration |
GET /api/v1/stripe/admin/config/history | Get configuration history |
GET /api/v1/stripe/admin/config/pull | Pull from Stripe |
POST /api/v1/stripe/admin/config/validate | Validate configuration |
POST /api/v1/stripe/admin/config/reset | Reset/archive all resources |
GET /api/v1/stripe/admin/webhooks | List webhooks with secrets |