# Quick Start (/docs/library/quickstart) import { Steps, Step } from 'fumadocs-ui/components/steps' import { Tabs, Tab } from 'fumadocs-ui/components/tabs' import { Callout } from 'fumadocs-ui/components/callout' # Quick Start Get your billing system running in 5 minutes. **Prerequisites:** Node.js 18+ and a [Commet account](https://commet.co). ## Install ```bash npm install @commet/node ``` ```bash pnpm add @commet/node ``` ```bash yarn add @commet/node ``` ```bash bun add @commet/node ``` ## Initialize ```typescript import { Commet } from '@commet/node' const commet = new Commet({ apiKey: process.env.COMMET_API_KEY!, environment: 'sandbox', // or 'production' }) ``` ## Subscribe to a Plan Each customer can have one active subscription at a time. ```typescript // Subscribe customer to a plan const subscription = await commet.subscriptions.create({ externalId: 'user_123', // Your user ID planId: 'plan_pro', billingInterval: 'monthly', initialSeats: { editor: 5 } }) ``` ## Track Usage ```typescript await commet.usage.track({ externalId: 'user_123', eventType: 'api_call', idempotencyKey: `evt_${Date.now()}`, properties: { endpoint: '/users', method: 'GET' } }) ``` ## Manage Seats ```typescript // Add seats await commet.seats.add({ externalId: 'user_123', seatType: 'editor', count: 5 }) // Set exact count await commet.seats.set({ externalId: 'user_123', seatType: 'editor', count: 10 }) ``` ## What's Next? * [Plans](/docs/library/features/plans) - List available plans * [Subscriptions](/docs/library/features/subscriptions) - Manage subscriptions * [Usage Events](/docs/library/features/usage-events) - Track consumption * [Seat Management](/docs/library/features/seat-management) - Manage licenses **Need help?** [support@commet.co](mailto:support@commet.co) # Onboarding (/docs/platform/onboarding) import { Callout } from 'fumadocs-ui/components/callout' import { Step, Steps } from 'fumadocs-ui/components/steps'; In this guide you'll find the steps to follow if it's your first time accessing Commet and you want to test its core functionalities. ### 1. Create an account To begin, you have two options: * **Sandbox:** Visit [https://sandbox.commet.co/login](https://sandbox.commet.co/login) to create a test account. This is ideal for exploring functionality and simulating real scenarios without risk. * **Production:** If you'd like to start directly in production, go to [https://commet.co/login](https://commet.co/login). In both cases, if it's your first time signing in, you'll be asked to complete some basic company information. ### 2. Create your products From the products tab, create your products, whether they're one-time, recurring, fixed, or tied to some metric created previously. Maybe your products are consumption-based or seat-based. You can create these metrics right there. Later, you'll be able to send events via API to test with real data. ### 3. Create a subscription A subscription is where all the conditions agreed upon with your customer come together. Each one can have different phases and will determine What and How we will charge our customers. Commet is also designed to be the source of truth for your customers. Therefore, if you don't have customers created, you'll need to create one at that moment to associate that subscription. ### 4. Simulation At this stage, you'll be able to simulate your subscription to see exactly how it would look. When the billing date set in the subscription arrives, Commet will send the invoice with the usage detail and charge the customer. In sandbox you won't be able to create a real subscription. ### 5. Next steps At this point, you have two options: **Option A: Get a production account** [Book a slot with our team](https://cal.com/guido-irigoyen/onboarding-meeting) so we can help you find the best plan for you. Our team will handle the migration of all your data so you can start operating with Commet in production as soon as possible. **Option B: Test with real data in Sandbox** Go to the API Keys section and start integrating the SDK to try Commet sandbox with real data. Check out our [Quick Start guide](/library/quickstart) to get up and running in under 5 minutes. This allows you to test the full functionality using your own data before moving to production. # Overview (/docs/platform/overview) import { Callout } from 'fumadocs-ui/components/callout' # Commet Billing Platform Commet is an all in one billing and payments solution. Create usage-based subscriptions, seat-based subscriptions, credit packages in 5 minutes and start charging globally. Commet is the tool for any dev or startup to monetize globally without dying in the attempt. Platform documentation is designed to explain the use of Commet. For SDKs, endpoints, and code examples, head to the [Developer Library Quick Start](/docs/library/quickstart). ## Why Commet? We believe that the next unicorns will be companies of no more than 20 people, obsessed with product and selling globally. That's why we want to help those teams stay focused on product, and not on building their billing, integrating payments, managing subscriptions or dealing with taxes and compliance. Commet provides: * **Flexible pricing models**: From simple subscriptions to complex usage-based pricing with tiers, seats and hybrid models * **Zero manual load on taxes and compliance**: If you're going to sell globally you'll have to pay taxes in more than one place. We do it. * **Global payments in 5 lines of code**: Integrate your subscription logic in 5 lines of code and start monetizing. * **Withdraw your money to your bank**: Withdraw the money collected from your customers net of taxes, directly to your local bank. * **Developer-first**: We believe that devs should be making product, not billing or payments. That's why we created a tool they love to use and can get back to their work. Commet Dashboard ## Key Capabilities ### Product Catalog and Pricing Define your products and pricing strategies however you imagine them. Including fixed subscriptions, usage-based, credit packages, tiers, licenses and hybrid combinations. ### Subscriptions Reflect any custom pricing, discounts and conditions. Handle everything from self-serve subscriptions to personalized negotiations. ### Agreements Create and manage customer contracts with custom pricing, discounts, and terms. Handle everything from self-serve subscriptions to enterprise negotiations with built-in approval workflows. ### Usage Tracking & Metering Ingest and process usage events in real-time. Track API calls, compute hours, storage, transactions—any metric that drives your pricing. [Learn about Usage Metrics →](../products/usage-based-pricing) ### Billing & Invoicing Automated billing cycles with support for prepaid, postpaid, and hybrid models. Generate compliant local invoices with proper tax handling for LATAM markets. ### Charge Globally and Don't Worry About Your Taxes Commet works as your Merchant of Record. Therefore we allow you to charge globally from day one without needing to register in other countries or manage the tax burden. ## What's next?

Products

Learn how to structure your products and pricing strategies

[Explore Pricing Types →](./features/products/catalog-overview)

Subscriptions

Set up customer subscriptions

[Explore Subscriptions →](./features/subscriptions/subscriptions-overview)

Usage Tracking and Metering

Track API calls, compute hours and custom usage metrics

[Explore Events →](./features/usage-metrics/events)

Seats and licenses

Charge globally in minutes and get the money in your bank

[Explore Seats →](./features/seats/seats-overview)

# CLI Commands (/docs/library/cli/commands) ## Authentication ### `commet login` Opens browser for OAuth authentication. Stores credentials in `~/.commet/auth.json`. ```bash commet login ``` ### `commet logout` ```bash commet logout ``` ### `commet whoami` Shows auth status and current organization. ```bash commet whoami ``` ## Project ### `commet link` Links project to an organization. Creates `.commet` file. ```bash commet link ``` ### `commet unlink` ```bash commet unlink ``` ### `commet switch` Switch to different organization (same environment). ```bash commet switch ``` ### `commet info` Shows current project and auth status. ```bash commet info ``` ## Types ### `commet pull` Generates `.commet/types.d.ts` with your event types, seat types, plans, and features. Enables autocomplete in your code. ```bash commet pull ``` After running, your SDK calls get autocomplete: ```typescript await commet.usage.track({ externalId: 'user_123', eventType: 'api_call', // ✓ autocomplete }) await commet.subscriptions.create({ externalId: 'user_123', planCode: 'pro', // ✓ autocomplete }) ``` ### `commet list events` ```bash commet list events ``` ### `commet list seats` ```bash commet list seats ``` # Configuration (/docs/library/cli/configuration) ## Files | File | Created by | Purpose | | --------------------- | -------------- | ----------------------------- | | `~/.commet/auth.json` | `commet login` | Global auth credentials | | `.commet` | `commet link` | Project organization settings | | `.commet/types.d.ts` | `commet pull` | Generated TypeScript types | ## Environments Two isolated environments: * **Sandbox** (`sandbox.commet.co`) - Development * **Production** (`commet.co`) - Live billing To switch: ```bash commet logout commet login # Select different environment commet link ``` ## Git Commit `.commet/types.d.ts` for consistent types across the team. The `.commet/` folder itself is auto-added to `.gitignore` by `commet pull`. # Installation (/docs/library/cli/installation) import { Tabs, Tab } from 'fumadocs-ui/components/tabs' import { Steps, Step } from 'fumadocs-ui/components/steps' # Installing Commet CLI Requires Node.js 18+. ## Install ```bash pnpm add -g commet ``` ```bash npm install -g commet ``` ```bash yarn global add commet ``` Verify: ```bash commet --version ``` ## Setup ### Authenticate ```bash commet login ``` Select environment (Sandbox/Production) and authenticate in browser. ### Link Project ```bash cd your-project commet link ``` Select your organization. ### Generate Types ```bash commet pull ``` Creates `.commet/types.d.ts` with your event and seat types. ## Update ```bash pnpm update -g commet ``` ```bash npm update -g commet ``` ```bash yarn global upgrade commet ``` # CLI Overview (/docs/library/cli/overview) Generate TypeScript types from your Commet dashboard for autocomplete in your code. ## Quick Start ```bash pnpm add -g commet commet login commet link commet pull ``` ## Commands | Command | Description | | -------- | ---------------------------- | | `login` | Authenticate with Commet | | `logout` | Remove credentials | | `link` | Link project to organization | | `pull` | Generate TypeScript types | | `info` | Show project status | See [Commands](/docs/library/cli/commands) for full reference. # Workflows (/docs/library/cli/workflows) ## Initial Setup ```bash pnpm add -g commet commet login commet link commet pull ``` ## Daily Development After adding types in the dashboard: ```bash commet pull ``` ## Switch Organizations ```bash commet switch ``` ## Switch Environments ```bash commet logout commet login # Select different environment commet link ``` # Error Handling (/docs/library/core/error-handling) ## Error Classes ```typescript import { CommetAPIError, CommetValidationError } from '@commet/node' try { await commet.customers.create({ email: 'invalid' }) } catch (error) { if (error instanceof CommetValidationError) { console.log(error.validationErrors) // { email: ['Invalid email format'] } } if (error instanceof CommetAPIError) { console.log(error.statusCode, error.message) } } ``` | Class | Use case | | ----------------------- | -------------------------------- | | `CommetAPIError` | HTTP errors (4xx, 5xx) | | `CommetValidationError` | Invalid input with field details | | `CommetError` | Base class for all errors | ## Automatic Retries Failed requests retry with exponential backoff (1s → 2s → 4s, max 8s). **Retryable:** 408, 429, 500, 502, 503, 504 ```typescript const commet = new Commet({ apiKey: process.env.COMMET_API_KEY!, retries: 3, // default }) ``` ## Non-Blocking Usage Don't let tracking errors break your app: ```typescript commet.usage.track({ externalId: 'user_123', eventType: 'api_call', }).catch(console.error) // Continue without waiting ``` # SDK Reference (/docs/library/core/reference) ## Setup ```typescript import { Commet } from '@commet/node' const commet = new Commet({ apiKey: process.env.COMMET_API_KEY!, }) ``` Get your API key from the [dashboard](https://commet.co/settings/api-keys). ## Options | Option | Type | Default | Description | | ------------- | ----------------------------- | ----------- | -------------------------------- | | `apiKey` | string | required | Your API key (starts with `ck_`) | | `environment` | `'sandbox'` \| `'production'` | `'sandbox'` | Target environment | | `debug` | boolean | `false` | Log requests/responses | | `timeout` | number | `30000` | Request timeout (ms) | | `retries` | number | `3` | Max retry attempts | ## Environments * **Sandbox** (`sandbox.commet.co`) - Development, default * **Production** (`commet.co`) - Live billing ```typescript commet.isSandbox() // true commet.isProduction() // false ``` ## Debug Mode See all requests and responses: ```typescript const commet = new Commet({ apiKey: process.env.COMMET_API_KEY!, debug: true, }) // [Commet SDK] POST https://sandbox.commet.co/api/customers // [Commet SDK] Response status: 200 OK ``` ## Pagination List endpoints use cursor-based pagination. ```typescript const page = await commet.customers.list({ limit: 25 }) if (page.hasMore) { const nextPage = await commet.customers.list({ limit: 25, cursor: page.nextCursor, }) } ``` | Parameter | Type | Default | Description | | --------- | ------ | ------- | ----------------------------- | | `limit` | number | 25 | Items per page (max 100) | | `cursor` | string | - | Cursor from previous response | # Testing (/docs/library/core/testing) Sandbox is the default environment - completely isolated from production. ## Test Cards **Successful payments:** | Card | Brand | | --------------------- | ---------- | | `4242 4242 4242 4242` | Visa | | `5555 5555 5555 4444` | Mastercard | Use any future expiry and any 3-digit CVC. **Failed payments:** | Card | Scenario | | --------------------- | ------------------ | | `4000 0000 0000 9995` | Insufficient funds | | `4000 0000 0000 0002` | Card declined | **3D Secure:** | Card | Description | | --------------------- | ----------------------- | | `4000 0025 0000 3155` | Requires authentication | ## Test Flow ```typescript // 1. Create customer const customer = await commet.customers.create({ email: 'test@example.com', externalId: `test_${Date.now()}`, }) // 2. Create subscription const subscription = await commet.subscriptions.create({ externalId: customer.data.externalId, planCode: 'pro', }) // 3. Pay with test card at checkoutUrl // 4. Track usage await commet.usage.track({ externalId: customer.data.externalId, eventType: 'api_call', }) ``` ## Production ```typescript const commet = new Commet({ apiKey: process.env.COMMET_PRODUCTION_KEY!, environment: 'production', }) ``` # Customer Context (/docs/library/features/customer) When working with a single customer, use `commet.customer()` to avoid repeating `externalId` on every call. ## Before vs After **Without Customer Context:** ```typescript await commet.usage.track({ externalId: 'user_123', eventType: 'api_call' }) await commet.seats.add({ externalId: 'user_123', seatType: 'editor', count: 1 }) await commet.features.check('custom_branding', 'user_123') await commet.subscriptions.get({ externalId: 'user_123' }) await commet.portal.getUrl({ externalId: 'user_123' }) ``` **With Customer Context:** ```typescript const customer = commet.customer('user_123') await customer.usage.track('api_call') await customer.seats.add('editor') await customer.features.check('custom_branding') await customer.subscription.get() await customer.portal.getUrl() ``` ## Available Methods All operations scoped to the customer: ```typescript const customer = commet.customer('user_123') // Features await customer.features.check('custom_branding') await customer.features.get('team_members') await customer.features.canUse('team_members') await customer.features.list() // Seats await customer.seats.add('editor', 5) await customer.seats.remove('editor', 2) await customer.seats.set('editor', 10) await customer.seats.getBalance('editor') // Usage await customer.usage.track('api_call', { endpoint: '/users' }) // Subscription await customer.subscription.get() // Portal await customer.portal.getUrl() ``` ## When to Use Use Customer Context when you're doing multiple operations for the same customer in one request - common in API routes and server actions. ```typescript export async function handleUserAction(userId: string) { const customer = commet.customer(userId) const { data } = await customer.features.canUse('api_calls') if (!data.allowed) { return { error: 'Upgrade required' } } await customer.usage.track('api_call') return { success: true } } ``` ## Related * [Features](/docs/library/features/features) * [Seats](/docs/library/features/seat-management) * [Usage](/docs/library/features/usage-events) # Customers (/docs/library/features/customers) ## Create Idempotent with `externalId` - if customer exists, returns it instead of creating duplicate. ```typescript await commet.customers.create({ email: 'billing@acme.com', externalId: 'user_123', }) ``` ## Get ```typescript const customer = await commet.customers.get('cus_xxx') ``` ## Update ```typescript await commet.customers.update('cus_xxx', { email: 'new@acme.com', }) ``` ## List ```typescript const customers = await commet.customers.list() ``` ## Related * [Subscriptions](/docs/library/features/subscriptions) * [Customer Portal](/docs/library/features/portal-access) # Features (/docs/library/features/features) ## Check Quick boolean check - use for gating features. ```typescript const { data } = await commet.features.check('custom_branding', 'user_123') if (!data.allowed) { redirect('/upgrade') } ``` ## Get Full details including usage numbers. ```typescript const feature = await commet.features.get('team_members', 'user_123') ``` ## Can Use Pre-flight check before adding seats - tells you if they'll be charged extra. ```typescript const { data } = await commet.features.canUse('team_members', 'user_123') if (!data.allowed) { return { error: 'Upgrade to add more members' } } if (data.willBeCharged) { // Show overage confirmation } ``` ## List ```typescript const features = await commet.features.list('user_123') ``` ## Related * [Subscriptions](/docs/library/features/subscriptions) * [Seats](/docs/library/features/seat-management) * [Plans](/docs/library/features/plans) # Plans (/docs/library/features/plans) Plans are configured in the [dashboard](https://commet.co). Use the SDK to list them or get details. ## List Plans ```typescript const plans = await commet.plans.list() ``` Include private plans: ```typescript const plans = await commet.plans.list({ includePrivate: true }) ``` ## Get Plan ```typescript const plan = await commet.plans.get('pro') ``` ## Related * [Subscriptions](/docs/library/features/subscriptions) * [Features](/docs/library/features/features) # Customer Portal (/docs/library/features/portal-access) Self-service portal where customers manage billing, update payment methods, and view invoices. ## Get URL URL is single-use and expires - generate fresh on each request. ```typescript const portal = await commet.portal.getUrl({ externalId: 'user_123' }) redirect(portal.data.portalUrl) ``` ## Next.js One-line setup with `@commet/next`. ```typescript title="app/api/commet/portal/route.ts" import { CustomerPortal } from '@commet/next' export const GET = CustomerPortal({ apiKey: process.env.COMMET_API_KEY!, getCustomerId: async (req) => { // Return user's externalId from your auth return 'user_123' }, }) ``` ```tsx Manage Billing ``` ## Related * [Next.js Setup](/docs/library/installation/nextjs) * [Subscriptions](/docs/library/features/subscriptions) # Seats (/docs/library/features/seat-management) Seat changes are billed at the end of the period (true-up model). ## Add ```typescript await commet.seats.add({ externalId: 'user_123', seatType: 'editor', count: 5, }) ``` ## Remove ```typescript await commet.seats.remove({ externalId: 'user_123', seatType: 'editor', count: 2, }) ``` ## Set Sets exact count - use when syncing from your system. ```typescript await commet.seats.set({ externalId: 'user_123', seatType: 'editor', count: 10, }) ``` ## Get Balance ```typescript const balance = await commet.seats.getBalance({ externalId: 'user_123', seatType: 'editor', }) ``` ## Related * [Subscriptions](/docs/library/features/subscriptions) * [Features](/docs/library/features/features) # Subscriptions (/docs/library/features/subscriptions) Each customer can only have one active subscription at a time. ## Create Returns a `checkoutUrl` - redirect user there to complete payment. ```typescript const subscription = await commet.subscriptions.create({ externalId: 'user_123', planCode: 'pro', }) redirect(subscription.data.checkoutUrl) ``` ## Get Returns full subscription details including feature usage summary. ```typescript const sub = await commet.subscriptions.get({ externalId: 'user_123' }) if (sub.data?.status === 'active') { // User has paid } ``` ## Change Plan Proration is automatic - credits unused time and charges for new plan. ```typescript await commet.subscriptions.changePlan('sub_xxx', { planCode: 'enterprise' }) ``` ## Cancel Cancels at end of current period by default. ```typescript await commet.subscriptions.cancel('sub_xxx') ``` ## Related * [Plans](/docs/library/features/plans) * [Usage](/docs/library/features/usage-events) * [Seats](/docs/library/features/seat-management) # Usage Events (/docs/library/features/usage-events) Usage is aggregated and billed at end of period. ## Track ```typescript await commet.usage.track({ externalId: 'user_123', eventType: 'api_call', }) ``` ## Batch More efficient for high-volume tracking. ```typescript await commet.usage.trackBatch({ events: [ { externalId: 'user_123', eventType: 'api_call' }, { externalId: 'user_456', eventType: 'api_call' }, ] }) ``` ## Related * [Subscriptions](/docs/library/features/subscriptions) * [Features](/docs/library/features/features) # Next.js Setup (/docs/library/installation/nextjs) import { Steps, Step } from 'fumadocs-ui/components/steps' import { Tabs, Tab } from 'fumadocs-ui/components/tabs' ## Install ```bash pnpm add @commet/node @commet/next ``` ```bash npm install @commet/node @commet/next ``` ```bash yarn add @commet/node @commet/next ``` ```bash bun add @commet/node @commet/next ``` ## Configure ```bash title=".env.local" COMMET_API_KEY=ck_sandbox_xxx COMMET_WEBHOOK_SECRET=whsec_xxx ``` ## Initialize ```typescript title="lib/commet.ts" import { Commet } from '@commet/node' export const commet = new Commet({ apiKey: process.env.COMMET_API_KEY!, environment: 'sandbox', }) ``` ## Create Subscription ```typescript title="app/actions/billing.ts" 'use server' import { redirect } from 'next/navigation' import { commet } from '@/lib/commet' export async function subscribe(externalId: string) { await commet.customers.create({ email: 'user@example.com', externalId, }) const subscription = await commet.subscriptions.create({ externalId, planCode: 'pro', }) redirect(subscription.data.checkoutUrl!) } ``` ## Handle Payment ```typescript title="app/api/webhooks/commet/route.ts" import { Webhooks } from '@commet/next' export const POST = Webhooks({ webhookSecret: process.env.COMMET_WEBHOOK_SECRET!, onSubscriptionActivated: async (payload) => { // Grant access to payload.data.externalId }, }) ``` ## Check Access ```typescript const subscription = await commet.subscriptions.get({ externalId: 'user_123' }) if (subscription.data?.status === 'active') { // User has paid } ``` ## Customer Portal ```typescript title="app/api/commet/portal/route.ts" import { CustomerPortal } from '@commet/next' export const GET = CustomerPortal({ apiKey: process.env.COMMET_API_KEY!, getCustomerId: async (req) => { // Return user's externalId from your auth return 'user_123' }, }) ``` ```tsx Manage Billing ``` ## Examples Full working examples to get you started: ## Related * [Node.js Setup](/docs/library/installation/node) * [Webhooks](/docs/library/features/webhooks) * [Customer Portal](/docs/library/features/portal-access) # Node.js Setup (/docs/library/installation/node) import { Steps, Step } from 'fumadocs-ui/components/steps' import { Tabs, Tab } from 'fumadocs-ui/components/tabs' ## Install ```bash pnpm add @commet/node ``` ```bash npm install @commet/node ``` ```bash yarn add @commet/node ``` ```bash bun add @commet/node ``` ## Configure ```bash title=".env" COMMET_API_KEY=ck_sandbox_xxx ``` ## Initialize ```typescript title="lib/commet.ts" import { Commet } from '@commet/node' export const commet = new Commet({ apiKey: process.env.COMMET_API_KEY!, environment: 'sandbox', }) ``` ## Use ```typescript // Create customer const customer = await commet.customers.create({ email: 'billing@acme.com', externalId: 'user_123', }) // Create subscription and get payment link const subscription = await commet.subscriptions.create({ externalId: 'user_123', planCode: 'pro', }) // Redirect user to pay redirect(subscription.data.checkoutUrl) ``` ## Check Subscription ```typescript const subscription = await commet.subscriptions.get({ externalId: 'user_123' }) if (subscription.data?.status === 'active') { // User has paid } ``` ## Check Features ```typescript const { data } = await commet.features.check('custom_branding', 'user_123') if (!data.allowed) { redirect('/upgrade') } ``` ## Related * [Customers](/docs/library/features/customers) * [Subscriptions](/docs/library/features/subscriptions) * [Usage](/docs/library/features/usage) # Acceptable Use Policy (/docs/platform/merchant-of-record/aceptable-use) import { Callout } from 'fumadocs-ui/components/callout' # Acceptable Use Policy Commet serves as your Merchant of Record, meaning we operate as the official reseller of your digital products and services. Our platform is designed specifically for digital offerings and does not accommodate physical items or services that depend on human delivery or manual fulfillment. Beyond the digital-only constraint, we maintain strict standards: we cannot process transactions for anything unlawful, dangerous, misleading, or that fails to meet our quality and trustworthiness criteria. **Have questions about your specific use case?** [Contact our support team](mailto:help@commet.co) before starting your integration. We can review your situation and offer personalized guidance. ## Restricted Categories Certain business types need extra scrutiny and must demonstrate elevated standards in quality, reliability, and regulatory compliance: * **eBooks**: Need to deliver real value and meet our quality benchmarks * **Ticket sales**: Must comply with regional regulations and legal requirements * **Pre-orders & paid waitlists**: Present higher risk for Merchant of Record operations; we may consider exceptions for established developers with proven delivery records * **Marketing services**: Should emphasize authentic, sustainable value over questionable shortcuts or bulk unsolicited communications * **Directories & boards**: Frequently feature paid positioning (essentially advertising) that may lack appropriate disclosure and compliance measures ## What You Can Sell Commet enables you to monetize these digital product and service categories: * **Premium access**: Subscription-based content, gated digital experiences, private GitHub repositories, Discord servers, and online educational courses * **Digital products**: Code repositories, templates, eBooks, PDFs, icons, fonts, design resources, photos, videos, audio files, and similar digital assets * **Software & SaaS**: Mobile applications, desktop software, web applications, and software-as-a-service offerings ### Core Requirements For your product or service to be eligible, it needs to meet these criteria: 1. **Compliant**: Must be lawful, ethical, transparent, and consistent with payment provider regulations 2. **High quality**: Should be something you'd confidently present publicly—avoid anything that undermines trust or quality expectations 3. **Digitally fulfillable**: Must be deliverable either automatically through Commet (access links, file downloads, license keys, invitations) or instantly available via your service using our APIs following purchase ## Prohibited Products & Services The categories listed below are not allowed on the Commet platform: **Note: This list is not comprehensive** We may introduce new restrictions at any point. Accounts could be subject to review or suspension if we identify usage patterns that are misleading, fraudulent, high-risk, or likely to generate excessive refunds or chargebacks. ### Compliance Violations * Services that breach terms of service on other platforms or services * Counterfeit products * Items you don't have ownership rights to or lack necessary licensing to resell * Intellectual property infringement or trademark violations ### Restricted Business Models * Travel-related services: reservations, travel clubs, timeshares * Recruitment platforms or job boards * Paid waitlists or pre-orders (we may make exceptions for high-trust scenarios with confirmed fulfillment) * Charitable donations or charity where pricing significantly exceeds product value (open source sponsorship arrangements may be eligible—reach out to discuss) ### Marketplaces & Reselling * Platforms that enable unauthorized resale or distribution * Unauthorized software license reselling * Marketplaces that sell products or services from other parties ### Financial Services * NFT and cryptocurrency assets * Financial guidance: investment strategies, trading signals, wealth management, tax advice, or related content and services * Investment advisory, brokerage, or trading services * Financial services: account balances, investments, or transaction facilitation ### Prohibited Service Types * Services designed to bypass rules or terms of other services * Cheating services: unauthorized modifications, hacks, or unfair advantages * IP or API cloaking services (evading rate limits, IP bans, etc.) * eSIM or telecommunication services * Malware, spyware, or viruses * IPTV services * Products or services that need special licensing or are heavily regulated * Wagering, betting, or gambling services ### Marketing & Outreach Services * Unsolicited marketing or advertising services, such as: * Automation for mass content generation and submission * Automated outreach that risks spam * Bulk messaging via SMS/WhatsApp * Lead selling, scraping, or generation ### Other Prohibited Categories * Services that could damage the reputation of Commet or our payment processing partners * "Get rich quick" content or schemes * Medical services: muscle building, weight loss, pharmaceutical products, or medical advice * Pseudo-science offerings: fortune-telling, horoscopes, clairvoyance ### Low-Quality Products * Deceptive practices: fake social proof, reviews, or testimonials * Products or services with low trustworthiness scores or misleading tactics * Services, websites, or products with major bugs or execution problems * Premium-priced AI-generated content (for example, $50 eBooks that are only 4 pages long) ### Adult Content & Services * Explicit or adult content, including: * NSFW content created through AI or other methods * Services similar to OnlyFans or related platforms * Adult services or content generated with AI ### Data & Privacy Violations * Services that undermine user privacy or data security * Unauthorized distribution or resale of customer data to third parties for promotional, commercial, or other unauthorized uses (disclosed service providers are permitted) ### Physical Goods & Human Services * Services that aren't digitally or automatically fulfillable * Professional services: web development, design, marketing, consulting, or other human-delivered services * Services that need physical delivery or fulfillment * Physical items of any type ### Illegal & Restricted Content * Content that conflicts with payment processor guidelines (for instance, [Stripe's restricted businesses](https://stripe.com/en-se/legal/restricted-businesses)) * Products that break laws in your operating jurisdiction or target markets * Services or content aimed at minors or that are age-restricted * Illegal products or services, such as vaping products, tobacco, alcohol, or drugs # Merchant of Record (/docs/platform/merchant-of-record/merchant-of-record) > A Merchant of Record that's a joy to use ### What is a Merchant of Record? As a Merchant of Record, we take on responsibility for global sales taxes on your behalf. So you can focus on growing your business instead of dealing with accounting invoices. Leave billing infrastructure, payments, and the headaches of international taxes to us. ### Payment Service Providers (PSPs) vs. Merchants of Record **Payment Service Providers (PSPs)** PSPs like Stripe provide an accessible, convenient abstraction to facilitate transactions over the underlying card networks and banks. * ✅ Powerful, flexible, low-level APIs for facilitating transactions * ✅ Can be used to power all business models and pricing under the sun * ❌ You are responsible for all tasks associated with transactions, e.g., international taxes, refunds, disputes * ❌ The APIs require more development and greater complexity even for common use cases **Merchants of Record (MoRs)** Merchants of Record provide an abstraction layer to facilitate digital transactions. * ✅ High-level dashboard, APIs, and SDKs to make payment infrastructure easy to use * ✅ The platform handles international sales taxes by acting as a reseller of your digital goods and services * ✅ Integrates other tasks like refunds, disputes, and pricing changes into a single platform * ❌ Higher fees per payment ### What should you choose? **Build and go to market with what you’re comfortable with** As in programming, abstractions are super useful to ship faster with fewer worries. So, what’s the ideal level of abstraction for you? Well, it depends. **Choose Stripe (PSP) if...** * Already integrated it? If you’re already in production — we’re devs, just keep shipping * You’re already comfortable with Stripe’s API * You want to handle all your event and subscription logic in-house * You’re comfortable handling international taxes yourself **Choose Commet (MoR) if...** * You want product, customer, pricing, and subscription management through an intuitive tool your whole team can use * You want to focus on building product and go live today * You don’t even want to think about handling international taxes and tax registrations yourself * You’re looking for a simple, developer-focused solution ### Our Vision: The Future of Tech Companies **We firmly believe the unicorns of the future will be startups with teams of 5 to 30 people.** In a world where technology enables small teams to build incredible products, monetization complexity shouldn’t be a barrier. Small teams need simple, powerful, developer-focused tools that let them: * Focus on building their product, not payment infrastructure * Scale globally from day one * Handle tax compliance without massive legal teams * Iterate quickly on monetization models **Commet exists to be the simplest, developer‑preferred tool for monetization.** We don’t aim to be the solution for every use case. But we want to be the tool small teams choose when they want to monetize simply, globally, and without hassle. # Finance Overview (/docs/platform/features/payouts/finance-overview) import { Tabs, Tab } from 'fumadocs-ui/components/tabs' import { Callout } from 'fumadocs-ui/components/callout' ## Overview The finance module handles three core functions: * **Balance tracking** - Where your money sits * **Payouts** - Getting money out * **Transaction history** - What happened when ## Balance States Your money exists in one of four states: * **Held** - Money we're holding (usually for compliance/risk reasons) * **Pending** - Money from transactions that's still processing * **Available** - Money ready to withdraw * **Paid Out** - Money already sent to your bank account Money sitting in Available for 90+ days gets auto-payout to your account. ## Payouts Account verification required before payouts. Once verified, request payouts for any amount ≥ $10. Money hits your bank account in 2-3 business days. Payout fee: 0.25% + $0.25 (Stripe's cost, not ours) ## Transaction History Complete audit trail of all money movement - incoming payments and outgoing payouts with status tracking. # Account Verification (/docs/platform/features/payouts/payouts-verification) import { Tabs, Tab } from 'fumadocs-ui/components/tabs' import { Callout } from 'fumadocs-ui/components/callout' ## Verification Required You can start accepting payments immediately, but you need verification to withdraw money. Stripe handles our compliance and KYC process. ## The Process 1. **Start verification** - Click "Verify Account" in the finance section 2. **KYC forms** - Provide business info and bank account details 3. **Wait for approval** - Usually takes a few days 4. **Start withdrawing** - Once approved, you can request payouts ## Security All verification happens through Stripe's secure environment with SOC 2 and ISO certifications. Your data is protected. Approval can take several days. We'll notify you when ready. # Product Catalog Business Logic (/docs/platform/features/products/business-logic) import { Tabs, Tab } from 'fumadocs-ui/components/tabs' import { Callout } from 'fumadocs-ui/components/callout' # Business logic & design This page connects the strategy behind the Product Catalog to the systems that execute it. Use it when you need to translate commercial ideas into catalog configuration or when you must explain pricing logic to stakeholders. Platform documentation aims at business operators. For SDKs, endpoints, and code samples head to the [Developer Library Quick Start](/docs/library/quickstart). ## Accessing the product catalog The product catalog is available through the **Products** section in your Commet platform. From here you can: * **View all products**: Browse your complete product portfolio with SKUs, descriptions, and tax categories * **Manage list prices**: Create and edit standard prices for each product across currencies and segments * **Configure price variants**: Set up customer-specific pricing with discounts, markups, or custom terms * **Link to agreements**: See which agreements reference specific prices or variants ## Why the catalog exists The catalog solves pricing-complexity management for billing platforms that juggle multiple pricing models and customer-specific terms. **Problems it eliminates** * Custom code for every new price or promotion. * Sales asking “What’s the official price?” vs. “What are we offering this customer?” * Lack of analytics on discount adoption or premium pricing. * No approval workflow for large enterprise concessions. * Pricing updates blocked behind engineering queues. **Business outcomes** * Clear list price vs. customer price conversations. * Accurate analytics for margins, discounts, and product performance. * Negotiation playbooks that combine list tiers and approved variants. * Automated governance that flags discounts beyond policy. * Freedom to support any business model without code changes. ## Four pricing layers working together Prices act as the core building blocks in Commet. Each price defines unit cost, pricing model, currency, billing frequency, and billing type. These prices can be reused across multiple customers, making catalog management efficient and scalable. ``` Products describe the services you sell: ├── API Platform → API access with rate limiting ├── Analytics Dashboard → Reporting and insights ├── Premium Support → 24/7 help with SLA ├── Data Storage → Scalable storage └── AI Processing → Machine learning services ``` ``` Product: API Platform ├── List Price: Starter → $50/month, 10K calls included ├── List Price: Professional → $200/month, 100K calls included ├── List Price: Enterprise → $500/month, 1M calls included └── List Price: Pay-per-use → $0.10 per call, no minimum ``` ``` List Price: Enterprise ($500/month) ├── Price Variant: Acme Corp → 20% discount = $400/month ├── Price Variant: MercadoLibre → $500/month, 2M calls included ├── Price Variant: Startup Beta → 50% discount = $250/month └── Price Variant: Enterprise Plus → 10% markup = $550/month ``` ``` Agreement: Acme Corp – Q1 2025 ├── Item 1: API Platform → Enterprise Plan (20% variant) ├── Item 2: Analytics Dashboard → Professional Plan (list price) ├── Item 3: Premium Support → Custom price variant └── Contract discount: 5% promo for Q1 ``` Each layer keeps analytics intact and separates permanent configuration (variants) from temporary negotiation tools (agreement discounts). ### Price reusability and identification Every price in the catalog has a unique `price_id` that serves as its identifier across the platform. This allows you to: * **Reuse standard prices** across multiple customers without duplication * **Track pricing changes** and maintain historical accuracy * **Reference prices** consistently in agreements, invoices, and analytics * **Create variants** from existing list prices while preserving the relationship ## Real-world catalogs **Company**: DevTools Inc. – API development platform 1. Start with Free → Starter → Pro → Enterprise list prices. 2. Add-ons such as Analytics or Priority Support live as separate products. 3. Enterprise deals add price variants (20% off, extra seats). 4. The agreement bundles everything so billing can generate accurate invoices. **Company**: PayFlow – payment processor * List prices capture standard, volume, and enterprise transaction fees. * Price variants store negotiated percentage rates and minimum commitments. * Additional products cover cross-border fees and chargeback insurance. * Agreements combine multi-product bundles with volume-based approvals. **Company**: AIFlow – machine learning platform * Products: compute hours, data scientist seats, model hosting. * List prices mix on-demand, reserved, and spot usage offers. * Variants track high-volume seat discounts and custom GPU bundles. * Agreements apply temporary promos while variants manage long-term terms. **Understanding Usage-Based Pricing** Usage metrics are the foundation of consumption-based pricing models. They track customer activity and convert it into billable units. **How usage metrics work:** 1. **Define the metric**: Create a usage metric that tracks specific customer behavior (API calls, storage GB, compute hours, transactions processed). 2. **Send usage events**: Your application reports usage events to Commet in real-time or in batches. 3. **Aggregate consumption**: The billing engine aggregates usage data for each billing period. 4. **Apply pricing rules**: Your configured pricing model (linear, tiered, packaged) calculates the charge. 5. **Generate invoices**: Usage charges appear as line items with consumption details. **Common usage metric examples:** * **API Platforms**: API calls, requests per minute, data transfer GB * **Infrastructure**: Compute hours, storage GB, bandwidth consumed * **Communications**: SMS sent, phone minutes, email deliveries * **AI/ML**: Model predictions, training hours, tokens processed * **Payment Processing**: Transaction volume, payment count **Pricing flexibility with usage metrics:** Usage metrics can be combined with multiple pricing models: * **Linear**: $0.10 per API call * **Graduated tiers**: First 100K calls @ $0.10, next 400K @ $0.08, 500K+ @ $0.05 * **Volume tiers**: 0-100K @ $0.10, 100K+ @ $0.07 (customer pays only their tier rate) * **Packaged**: $25 per 1,000 API calls * **With included units**: First 10K calls free, then $0.10 per call * **Credit burndown**: 50K API credits pack, 1 call = 5 credits **Best practices:** * Name metrics clearly (e.g., "api-calls" not "metric-1") * Choose appropriate aggregation (sum for API calls, max for concurrent users, unique for monthly active users) * Set up alerts for unusual consumption patterns * Provide customers with real-time usage dashboards * Include usage details in invoices for transparency ## Supported pricing models | Model | Use case | Example | | ------------------------- | ------------------------------------------------ | -------------------------------------------------- | | **Fixed / subscription** | Predictable revenue, monthly or one-time fees. | $500/month platform fee, $2,500 onboarding | | **Linear usage** | Pay-per-use with included units. | $0.10 per API call after 1,000 free calls | | **Percentage-based** | Payments or revenue-sharing with safeguards. | 2.9% of transaction value with $0.30 min / $10 max | | **Volume tiers** | Customer pays the rate of the tier they land in. | 0–100 units @ $1 + $20 flat, 101+ @ $0.75 + $50 | | **Graduated tiers** | Progressive pricing like tax brackets. | First 100 GB @ $1, remaining @ $0.75 | | **Packaged / stair-step** | Sell bundles of units. | $10 per 250 SMS sent | | **Seat-based** | Billing tied to seat balances. | $50 per admin seat per month | | **Minimum fees** | Guarantee baseline revenue. | $500 monthly minimum applied across usage prices | | **Credit burndown** | Prepaid credits with rollover. | 2,500 credits pack, 10 credits per API call | Code-friendly examples live in the developer docs, but the catalog UI exposes each model as configurable options. ## Governance rules **When to create a product** 1. New value proposition or service line. 2. Different tax treatment. 3. Separate reporting needs. **When to publish a list price** 1. New segment or market positioning. 2. Different commitment period or included units. 3. Switching pricing models (fixed vs. usage vs. tiers). **When to use a price variant** 1. Customer-specific discount or currency. 2. Contracted unit changes or volume commitments. 3. Long-lived custom terms (not temporary promos). **When to apply agreement discounts** * Ramp-up phases, quarter promotions, or limited-time incentives. * Layered on top of list prices and variants without breaking analytics. ## Multi-tenant flexibility Each organization running on Commet can configure its own catalog: * **Startup catalog**: a single core product with 4 plans, a couple of add-ons, minimal variants. * **Enterprise catalog**: multiple products, professional services, dozens of variants with approvals, aggressive discount policies. The catalog supports both extremes on the same infrastructure, keeping segmentation, discount policies, and reporting separate. ## Billing engine integration All billing internals live in `billing-engine.md`, but here’s the high-level handshake: * Products provide tax categories and descriptions for invoices. * List prices act as the official baseline for negotiations. * Price variants inject permanent customer customization. * Pricing models (fixed, usage, seats, tiers) feed the billing calculator. * Agreements combine everything and pass it downstream for invoice generation. ```typescript function resolveFinalPricing(agreementItem: AgreementItem) { const listPrice = getListPrice(agreementItem.listPriceId); let finalAmount = listPrice.unitAmount; if (agreementItem.priceVariantId) { const variant = getPriceVariant(agreementItem.priceVariantId); finalAmount = applyVariantPricing(finalAmount, variant); } if (agreementItem.agreementDiscountType) { finalAmount = applyAgreementDiscount(finalAmount, agreementItem); } return { listPrice, finalAmount }; } ``` ## Integration points with other modules * **Usage module**: `price_variant.usage_metric_id → usage_metric.id` to track consumption. * **Seats module**: `agreement_item.quantity_source = 'seat_balance'` pulls seat counts automatically. * **Tax module**: `product.tax_category_id → tax_category.id` applies correct rates per product. * **Customer module**: optional `price_variant.customer_id` to tie custom pricing to a specific account. ## End-to-end workflow 1. **Catalog setup**: define the product portfolio and assign tax categories. 2. **List price design**: product marketing publishes official pricing for each segment. 3. **Negotiation**: sales crafts price variants with approvals for custom deals. 4. **Contract signing**: agreements reference list prices, variants, and temporary discounts. 5. **Billing automation**: the billing engine executes the cascade and produces transparent receipts. ## Key success metrics * Zero pricing errors in invoices. * Full pricing-model coverage without engineering involvement. * Sub-two-second pricing calculations even with complex tiers. * No manual adjustments due to catalog limitations. ## Troubleshooting common scenarios | Scenario | Root cause | Solution | | -------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ | | Invoice shows wrong price | Variant or agreement discount not applied | Verify `agreement_item` links correct `price_variant_id` and discount settings | | Tax calculation missing | Product missing `tax_category_id` | Assign tax category to product before creating list prices | | Pricing resolution timeout | Complex tier calculations with many variants | Optimize tier structure or cache frequently-used pricing paths | | Discount approval bypassed | No policy enforcement on variant creation | Enable approval workflows in RevOps settings | # Product Catalog Overview (/docs/platform/features/products/catalog-overview) import { Callout } from 'fumadocs-ui/components/callout' # Product Catalog System The product catalog is the single source of truth for everything related to pricing. It keeps sales, finance, and product aligned so that changing a price never requires a code deploy again. The Platform area is designed for go-to-market, finance, and operations teams. If you need implementation details or APIs, jump to the [Developer Library](/docs/library/quickstart). ## Quick start example Here's how a typical SaaS company structures their catalog: 1. **Create a product**: "API Platform" 2. **Add list prices**: Free ($0), Starter ($50/mo), Enterprise ($500/mo) 3. **Negotiate a variant**: Enterprise with 20% discount for Acme Corp 4. **Sign an agreement**: Bundle API Platform + Support, apply a Q1 promo The billing engine automatically resolves: List → Variant → Agreement → Final invoice. ## Why the catalog matters * **No more pricing chaos**: every price lives in one catalog instead of being hardcoded in custom deals. * **Faster updates**: launch a new plan or tweak a price directly from the catalog—no code deploys required. * **Multi-currency support**: configure prices in different currencies for global customers. * **Quote generation**: use list prices as templates for customer quotes and proposals. ## 4-layer pricing architecture | Layer | Purpose | Example | | ----------------- | --------------------------------------------------------------------------- | ----------------------------------- | | **Product** | Defines what you sell (API platform, analytics dashboard, premium support). | “API Platform” | | **List Price** | Official commercial plan ready for quoting. | “Enterprise Plan” at $500/month | | **Price Variant** | Customer-specific terms (discounts, currencies, unit changes). | “Acme Enterprise – 20% discount” | | **Agreement** | The signed contract that bundles products, variants, and promotions. | “Acme Corp – FY25 Master Agreement” | ## Business outcomes * **Sales enablement**: “List price $500, your discount 20%” becomes a standard conversation. * **Revenue control**: finance monitors margins and discount thresholds in real time. * **Product strategy**: PMs launch plans without engineering handoffs. * **Customer transparency**: agreements show every component and its price origin. ## How to use the catalog ### View products and prices 1. Navigate to **Products** in the platform 2. Browse your product catalog to see all products or create a new one 3. Click on any product to view its list prices and price variants 4. Review pricing by currency, segment, or customer ### Create a list price 1. Select a product from your catalog 2. Click **Create List Price** 3. Configure the pricing details: * Display name (e.g., "Enterprise Annual Plan") * Billing frequency (monthly, annual, one-time) * Pricing model (fixed, usage-based, tiered) * Currency and amount 4. Save the list price—it becomes available for quotes and billing schedules ### Use products in agreements **For billing agreements:** 1. Reference list prices or price variants in agreements 2. Apply adjustments: * Discounts or markups * Modified unit amounts * Custom included units * Different currency * Add minimum commitments 3. Automatically Commet creates a price variant for this customer. 4. The billing engine automatically calculates based on the pricing cascade. 5. Invoices show clear line items with pricing origin ## Example journeys ### SaaS with a freemium ladder 1. Publish a progression of plans (Free → Starter → Pro → Enterprise). 2. Attach add-ons like "Advanced Analytics" or "Priority Support". 3. When an enterprise customer negotiates, create a price variant with a volume discount. 4. Bundle everything inside the agreement so billing picks it up automatically. ### Payments company with percentage-based pricing 1. Keep standard, volume, and enterprise rates in list prices. 2. Capture international fees and chargeback protection as separate products. 3. Use price variants to record negotiated percentages and minimum volume commitments. ### AI/ML platform combining seats and usage 1. Products for compute hours, data scientist seats, and model hosting. 2. Reserved capacity and on-demand usage live side-by-side in the catalog. 3. Variants store custom seat pricing for high-volume commitments while agreements handle temporary promotions. ## Built-in pricing models The catalog supports nine pricing models out of the box: * Fixed or subscription (monthly, annual, one-time). * Per-unit usage with included units. * Percentage-based fees with min/max caps. * Volume tiers (pay the tier you land in). * Graduated tiers (pay every tier along the way). * Packaged or stair-step bundles. * Seat-based billing powered by the Seats module. * Minimum fees that apply across several variants. * Credit burndown with rollover logic. > Need implementation details? See the [Product Catalog Business Logic](./business-logic) page or jump straight to the [developer docs](/docs/library/quickstart). ## Decision guardrails * Create a **new product** when the value proposition, tax category, or service type changes. * Publish a **new list price** when targeting a new segment, commitment period, or pricing model. * Use a **price variant** when a customer needs permanent custom terms. * Apply an **agreement discount** for temporary promotions or ramp periods. ## Success metrics to monitor * Zero pricing errors in invoices. * Complete coverage of every business pricing model. * Pricing calculations resolve in under two seconds. * No manual adjustments caused by catalog limitations. ## Common pitfalls to avoid * **Hardcoding prices outside the catalog**: always route pricing through list prices or variants to maintain analytics integrity. * **Using agreement discounts for long-term terms**: prefer price variants for permanent customer-specific pricing. * **Skipping tax category assignment**: every product needs a tax category for compliant invoicing. * **Creating too many products**: consolidate similar offerings under one product with multiple list prices instead. # Seat-Based Pricing (/docs/platform/features/products/seat-based-pricing) import { Tabs, Tab } from 'fumadocs-ui/components/tabs' import { Callout } from 'fumadocs-ui/components/callout' # Seat-Based Pricing Seat-based pricing allows you to charge customers based on the number of users, seats, or licenses they have active in their account. This model is perfect for team collaboration tools, SaaS platforms, and enterprise software where value scales with team size. Platform documentation aims at business operators. For SDKs, endpoints, and code samples head to the [Developer Library Quick Start](/docs/library/quickstart). ## Why seat-based pricing Seat-based pricing creates predictable revenue while aligning costs with customer team growth. As teams expand, revenue grows proportionally, making it one of the most popular SaaS pricing models. **Problems it solves:** * Unpredictable revenue from usage-only models * Complex capacity planning for unlimited user access * Difficulty pricing multi-user products fairly * Tracking who's using your product and how much * Managing enterprise contracts with minimum commitments **Business outcomes:** * Predictable monthly recurring revenue (MRR) * Revenue scales automatically with customer growth * Clear pricing that's easy to understand and forecast * Flexible seat management with minimums and overages * Enterprise-ready with tiered volume discounts ## How seat-based pricing works ``` ┌─────────────────┐ │ User Management│ Admin adds/removes team members │ │ (Slack, GitHub, Notion, etc.) └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Seat Balance │ Real-time tracking of active seats │ │ { customer, seatType, quantity } └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Pricing Engine │ Applies seat-based pricing model │ │ (Linear, Tiered, with minimums) └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Invoice │ "20 seats × $50 = $1,000" │ │ + prorated additions if mid-cycle └─────────────────┘ ``` ### 1. Define seat types Create different seat types for various user roles: ```typescript // Example: Different seat types by role { id: "admin-seat-uuid", name: "Admin Seat", key: "admin_seat", description: "Full platform access with admin privileges" } { id: "editor-seat-uuid", name: "Editor Seat", key: "editor_seat", description: "Content creation and editing access" } { id: "viewer-seat-uuid", name: "Viewer Seat", key: "viewer_seat", description: "Read-only access" } ``` ### 2. Configure seat pricing Set up pricing for each seat type: ```typescript // Linear pricing: $50 per admin seat { pricingModel: "per_unit", unitAmount: 5000, // $50 per seat currency: "USD", billingInterval: "monthly", billInAdvance: false, // Arrears (charge at end) quantitySource: "seat_balance", seatTypeId: "admin-seat-uuid" } ``` ### 3. Automatic seat tracking Commet tracks seat changes in real-time: * **Seat additions**: Automatically prorated for mid-cycle adds * **Seat removals**: Applied at next billing cycle or immediately * **Seat balance**: Current count of active seats per type * **History**: Audit trail of all seat changes ### 4. Billing automation Invoices are generated automatically: ``` Admin Seats 20 seats × $50.00 = $1,000.00 Editor Seats 5 seats × $30.00 = $150.00 Total: $1,150.00 ``` ## Seat-based pricing models **Linear seat-based pricing** Same price per seat regardless of quantity. Simple and predictable. ```typescript { pricingModel: "per_unit", unitAmount: 5000, // $50 per seat currency: "USD", billingInterval: "monthly", billInAdvance: false, // Arrears quantitySource: "seat_balance", seatTypeId: "standard-seat-uuid" } // 20 seats × $50 = $1,000 // 100 seats × $50 = $5,000 ``` **Real-world examples:** * **Figma**: $15/editor/month (flat rate) * **Notion**: $10/user/month (flat rate for Plus) * **Linear**: $8/user/month (flat rate) **When to use:** * Simple, transparent pricing needed * No volume discount strategy * Small to medium team sizes (\< 50 users) * Want to keep pricing straightforward **Graduated seat-based pricing** Price per seat decreases as quantity increases, rewarding larger teams. ```typescript { pricingModel: "tiered", tierType: "graduated", quantitySource: "seat_balance", seatTypeId: "enterprise-seat-uuid" } // Tiers configured separately price_variant_tier: [ { tierOrder: 1, upTo: 15, unitAmount: 5000, // First 15 seats @ $50 flatFee: 0 }, { tierOrder: 2, upTo: 50, unitAmount: 4000, // Next 35 seats @ $40 flatFee: 0 }, { tierOrder: 3, upTo: null, // 50+ seats unitAmount: 3000, // @ $30 flatFee: 0 } ] ``` **Calculation example for 60 seats:** ``` Tier 1: 15 seats × $50 = $750 Tier 2: 35 seats × $40 = $1,400 Tier 3: 10 seats × $30 = $300 ──────────────────────────── Total: $2,450/month ``` **Real-world examples:** * **Slack**: Volume discounts for larger teams * **GitHub**: Enterprise pricing scales with seats * **Salesforce**: Progressive per-user pricing **When to use:** * Targeting enterprise customers * Want to incentivize team growth * Competitive in large team market * Need volume discount strategy **Seat pricing with contracted minimums** Guarantee minimum seats billed, charge for overages. ```typescript // Agreement configuration { minimumSeats: 50, // Contracted minimum actualSeats: 45, // Current usage billedSeats: 50 // Bill for minimum } // Next month if seats grow { minimumSeats: 50, actualSeats: 65, // Grew beyond minimum billedSeats: 65 // Bill for actual (overage) } ``` **How it works:** | Scenario | Minimum | Actual | Billed | Calculation | | ------------- | ------- | ------ | ------ | ----------------- | | Under minimum | 50 | 35 | 50 | 50 × $50 = $2,500 | | At minimum | 50 | 50 | 50 | 50 × $50 = $2,500 | | Over minimum | 50 | 75 | 75 | 75 × $50 = $3,750 | **Real-world examples:** * **Enterprise contracts**: "Minimum 100 seats commitment" * **Annual deals**: Guaranteed minimums for discount * **Volume agreements**: "Minimum $10K/month spend" **When to use:** * Enterprise sales contracts * Annual commitments with discounts * Guaranteed revenue minimums * Protect against seat fluctuation ## Billing timing: Advance vs Arrears ### Arrears billing (charge at end) Charge for seats used during the **previous** billing period. ```typescript { billInAdvance: false // Arrears } ``` **How it works:** 1. March 1-31: Customer uses 20 seats 2. April 1: Invoice generated for March usage 3. Customer billed: 20 × $50 = $1,000 **Advantages:** * Charge for actual usage * Fair for customers adding/removing seats * No refunds needed for seat removals * Easier to explain "you pay for what you used" **Use cases:** * Monthly seat fluctuations expected * Trial/onboarding periods * Startups with changing team sizes ### Advance billing (charge upfront) Charge for seats for the **upcoming** billing period. ```typescript { billInAdvance: true // Advance } ``` **How it works:** 1. March 1: Invoice for March 1-31 usage 2. Customer pre-pays: 20 × $50 = $1,000 3. March 1-31: Customer uses the pre-paid seats **Advantages:** * Predictable cash flow * Revenue recognized upfront * Reduces churn (prepaid = commitment) * Standard SaaS practice **Use cases:** * Stable enterprise teams * Annual contracts * SaaS standard practice * Need cash flow predictability ## Proration for mid-cycle changes ### Adding seats mid-cycle When seats are added during a billing period, customers are charged a prorated amount. **Example: Monthly billing, arrears** ``` Billing period: March 1-31 (31 days) Starting seats: 10 @ $50/seat March 15: Add 5 seats (17 days remaining) Calculation: - Original 10 seats: 31 days × $50 = $500 - New 5 seats: 17/31 days × $50 × 5 = $137.10 - Total March invoice: $637.10 ``` **Proration formula:** ```typescript proratedAmount = (daysRemaining / totalDays) × seatPrice × seatsAdded ``` ### Removing seats mid-cycle **Arrears billing**: No proration needed (billed at end for actual usage) **Advance billing**: Credit applied to next invoice or refunded ## Common seat-based pricing strategies ### Strategy 1: Role-based seat pricing Different prices for different user types. ```typescript // Admin seats: Full access { seatTypeId: "admin-seat", unitAmount: 10000 // $100/seat } // Editor seats: Content access { seatTypeId: "editor-seat", unitAmount: 5000 // $50/seat } // Viewer seats: Read-only { seatTypeId: "viewer-seat", unitAmount: 1000 // $10/seat } ``` **Real-world examples:** * **Figma**: Editors ($15) vs Viewers (free) * **Miro**: Full members vs Guests * **Notion**: Members vs Guests pricing **When to use:** * Clear value difference between roles * Want to monetize all user types * Encourage wider adoption with cheap viewers * Complex permission systems ### Strategy 2: Hybrid seat + usage Combine seat-based baseline with usage overages. ```typescript // Base: Seat pricing { seatTypeId: "developer-seat", unitAmount: 5000, // $50/seat includedUsage: 10000 // 10K API calls included per seat } // Overage: Usage pricing { pricingModel: "per_unit", unitAmount: 100, // $0.01/call for overages usageMetricId: "api-calls" } ``` **Example billing:** ``` 10 Developer Seats × $50 = $500/month Included: 100K API calls (10K per seat) Actual usage: 150K calls Overage: 50K × $0.01 = $500 Total: $500 (seats) + $500 (overage) = $1,000 ``` **When to use:** * Usage varies significantly per user * Want predictable base + flexible ceiling * Avoid bill shock from pure usage pricing * Common in API platforms, infrastructure ### Strategy 3: Tiered plans with seat limits Fixed plans with included seat ranges. ``` Starter Plan: $99/month ├── Up to 5 seats included └── $20 per additional seat Professional Plan: $299/month ├── Up to 20 seats included └── $15 per additional seat Enterprise Plan: Custom pricing ├── Unlimited seats └── Volume discounts available ``` **When to use:** * Want simple plan tiers * Packaging strategy (good-better-best) * Small teams prefer all-inclusive pricing * Reduce pricing complexity ## Seat management best practices ### Tracking seat usage **Automatic sync from your app:** ```typescript // Add seat await commet.seats.add({ customerId: "customer-uuid", seatTypeId: "admin-seat-uuid", userId: "user-123", email: "john@acme.com", effectiveDate: new Date() }); // Remove seat await commet.seats.remove({ customerId: "customer-uuid", seatId: "seat-uuid", effectiveDate: new Date() // or future date }); // Get current balance const balance = await commet.seats.getBalance({ customerId: "customer-uuid", seatTypeId: "admin-seat-uuid" }); // Returns: { quantity: 20, lastUpdated: "2025-01-15" } ``` ### Customer transparency **Real-time seat dashboards:** * Show current seat count vs contracted minimum * Display cost per seat and total monthly cost * Preview impact of adding/removing seats * Show proration calculations before confirming **Seat usage alerts:** * Notify when approaching contracted minimum * Alert when adding seats mid-cycle (proration warning) * Remind before billing cycle for seat optimization ### Governance and controls **Seat limits:** ```typescript { minimumSeats: 10, // Contract minimum maximumSeats: 100, // Hard cap (optional) currentSeats: 45, // Actual usage allowOverages: true // Can exceed minimum } ``` **Approval workflows:** * Require admin approval for seat additions * Finance approval for overages beyond threshold * Automatic notifications for seat changes ## Troubleshooting seat-based billing | Issue | Cause | Solution | | ------------------------------ | -------------------------------- | -------------------------------------------- | | Seats not appearing on invoice | Seat added after period close | Ensure seats added before billing cycle ends | | Proration incorrect | Wrong effective date | Verify seat addition date is accurate | | Billed for removed seats | Seats not removed in system | Audit seat balance vs active users | | Customer disputes seat count | Mismatch between app and billing | Implement daily seat sync reconciliation | | Minimum not enforced | Agreement configuration missing | Check agreement has minimumSeats set | | Overage charges unexpected | Customer unaware of minimums | Display seat limits in customer dashboard | ## Real-world examples by industry ### SaaS Collaboration Tools **Example: Project management platform** ``` Product: "TaskFlow Pro" Seat Types: ├── Admin Seat: $50/month (unlimited projects) ├── Member Seat: $30/month (assigned projects only) └── Guest Seat: $10/month (view-only, limited projects) Pricing Strategy: - Graduated tiers: 1-15 seats (full price), 16-50 (10% off), 51+ (20% off) - Annual discount: 20% off when billed annually - Minimum: Enterprise contracts require 25 seat minimum ``` ### Developer Tools **Example: API development platform** ``` Product: "DevTools API Platform" Seat Types: ├── Developer Seat: $99/month │ ├── Included: 100K API calls/month │ ├── Included: 5 projects │ └── Overage: $0.01/call beyond included Pricing Strategy: - Hybrid: Seat-based + usage overages - Team discounts: 10+ seats get 15% off - Arrears billing: Charge for actual seats used ``` ### Enterprise Software **Example: CRM platform** ``` Product: "SalesPro CRM" Plans: ├── Starter: $25/user/month (up to 10 users) ├── Professional: $75/user/month (11-100 users) └── Enterprise: Custom pricing (100+ users) Features: - Volume discounts on Professional (10% off 50+ seats) - Annual contracts: Minimum 50 seats, 25% discount - Advance billing: Lock in pricing for 12 months ``` # Usage-Based Pricing (/docs/platform/features/products/usage-based-pricing) import { Tabs, Tab } from 'fumadocs-ui/components/tabs' import { Callout } from 'fumadocs-ui/components/callout' # Usage-Based Pricing Usage-based pricing allows you to charge customers based on their actual consumption of your product or service. Instead of flat monthly fees, customers pay for what they use—whether that's API calls, storage gigabytes, compute hours, or transactions processed. Platform documentation aims at business operators. For SDKs, endpoints, and code samples head to the [Developer Library Quick Start](/docs/library/quickstart). ## Why usage-based pricing Usage-based pricing aligns your revenue directly with customer value. As customers consume more of your service, they pay more. This creates fair pricing that scales naturally with customer growth. **Problems it solves:** * Customers overpaying for unused capacity in fixed plans * Difficulty acquiring price-sensitive customers who want to start small * Revenue not scaling with actual product usage * Complex pricing negotiations for variable consumption * Lack of transparency in what customers actually pay for **Business outcomes:** * Revenue scales automatically with customer success * Transparent billing that builds trust * Flexible pricing that accommodates all customer sizes * Data-driven insights into feature usage and value ## How usage metrics work Usage metrics are the foundation of consumption-based pricing. Here's the complete flow: ``` ┌─────────────────┐ │ Application │ Your app tracks customer activity │ │ (API calls, storage, transactions) └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Usage Events │ Real-time or batch event reporting │ │ { customer, metric, quantity, timestamp } └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Commet │ Aggregates events by billing period │ Aggregation │ Sum, Count, Max, Unique calculations └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Pricing Engine │ Applies pricing model to aggregated usage │ │ (Linear, Tiered, Packaged, Percentage) └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Invoice │ Detailed line items with usage breakdown │ │ "25,000 API calls × $0.10 = $2,500" └─────────────────┘ ``` ### 1. Define your usage metric Create a usage metric that tracks specific customer behavior: ```typescript // Example: API calls usage metric { id: "api-calls-metric-uuid", name: "API Calls", key: "api_calls", aggregationType: "sum", // sum, max, unique, count unitLabel: "calls" } ``` **Common aggregation types:** * **Sum**: Total units consumed (API calls, storage GB, compute hours) * **Max**: Peak concurrent usage (max simultaneous connections, peak compute) * **Unique**: Distinct count (monthly active users, unique API keys used) * **Count**: Number of events (transactions, deployments, builds) Usage Metrics Table The usage metrics configuration shows how each metric is defined with its event type (user\_activity, data\_processing, payment\_transaction, api\_call) and aggregation method (Count, Sum, Unique) to properly track and bill consumption. ### 2. Send usage events Your application reports usage to Commet: ```typescript // Real-time usage tracking await commet.usage.track({ customerId: "customer-uuid", metricKey: "api_calls", quantity: 1, timestamp: new Date(), metadata: { endpoint: "/v1/users", responseTime: "120ms" } }); // Batch reporting for efficiency await commet.usage.batchTrack([ { customerId: "...", metricKey: "api_calls", quantity: 150 }, { customerId: "...", metricKey: "storage_gb", quantity: 25.5 } ]); ``` Usage Events Table The usage events table shows individual tracking events with Event IDs, event types (sms\_notification, api\_call, payment\_transaction), customer assignments, and precise timestamps for accurate billing period assignment. ### 3. Automatic aggregation Commet aggregates usage data for each billing period: * **Daily aggregation**: For real-time dashboards and alerts * **Billing period aggregation**: For invoice generation * **Historical tracking**: For analytics and trending ### 4. Apply pricing rules Your configured pricing model calculates charges automatically: ```typescript // Linear pricing: $0.10 per API call { pricingModel: "per_unit", unitAmount: 1000, // $0.10 in cents usageMetricId: "api-calls-metric-uuid", includedUnits: 10000 // First 10K calls free } // Usage: 35,000 calls // Calculation: (35,000 - 10,000 free) × $0.10 = $2,500 ``` ### 5. Generate transparent invoices Usage charges appear as detailed line items: ``` API Calls Usage 35,000 calls × $0.10 = $3,500.00 (10,000 included units, 25,000 billable units) ``` ## Usage-based pricing models **Linear per-unit pricing** Charge a fixed rate per unit consumed. Simple, predictable, and easy to understand. ```typescript { pricingModel: "per_unit", unitAmount: 1000, // $0.10 per call usageMetricId: "api-calls-uuid", includedUnits: 1000 // 1,000 free calls } ``` **Real-world examples:** * **Twilio**: $0.0075 per SMS sent * **OpenAI**: $0.002 per 1K tokens (GPT-3.5) * **AWS Lambda**: $0.20 per 1M requests **When to use:** * Simple consumption-based services * Predictable unit economics * Clear value per unit (API calls, messages, compute hours) **Percentage-based pricing** Charge a percentage of transaction value, perfect for payment processing or revenue-sharing models. ```typescript { pricingModel: "per_unit", isPercentageBased: true, percentageRate: 290, // 2.9% in basis points minFeePerUnit: 30, // $0.30 minimum per transaction maxFeePerUnit: 1000, // $10.00 maximum per transaction usageMetricId: "payment-amount-uuid" } ``` **Calculation examples:** * $10 transaction: 2.9% = $0.29 → $0.30 (minimum applied) * $100 transaction: 2.9% = $2.90 → $2.90 * $500 transaction: 2.9% = $14.50 → $10.00 (maximum applied) **Real-world examples:** * **Stripe**: 2.9% + $0.30 per transaction * **PayPal**: 2.99% + $0.49 per transaction * **Shopify Payments**: 2.4% + $0.30 per transaction ### Percentage Pricing with Thresholds When using percentage-based pricing, you can set optional **minimum and maximum fees per unit** to control edge cases: * **Min fee** (`minFeePerUnit`): Ensures minimum revenue per transaction (protects against micropayments) * **Max fee** (`maxFeePerUnit`): Caps the maximum charge per transaction (protects customers from excessive fees) **Configuration example:** Percentage Pricing Configuration The percentage pricing configuration shows how to set up thresholds with Type: Percentage selected, including the percentage rate (2.9%), optional minimum fee ($0.30), and optional maximum fee ($10.00) to control edge cases in transaction-based pricing. **How thresholds work:** | Payment Amount | 2.9% Calculated | Threshold Applied | Final Charge | | -------------- | --------------- | ----------------- | ------------ | | $5 | $0.15 | Min → $0.30 | **$0.30** | | $50 | $1.45 | None | **$1.45** | | $500 | $14.50 | Max → $10.00 | **$10.00** | **When to use thresholds:** * **Min fee**: Payment processors, SMS providers, micropayment platforms * **Max fee**: Large transaction platforms, enterprise contracts, high-value marketplaces * **Both**: Balanced revenue protection for variable transaction sizes **Difference vs Fixed Fee:** ```typescript // Thresholds (replace percentage if outside range) { percentageRate: 200, // 2% minFeePerUnit: 100, // Charge $1 IF 2% < $1 maxFeePerUnit: 1000, // Charge $10 IF 2% > $10 } // Fixed Fee (ALWAYS add both) { percentageRate: 290, // 2.9% fixedFeePerUnit: 30, // ALWAYS + $0.30 } // $100 → 2.9% ($2.90) + $0.30 = $3.20 ``` **When to use:** * Payment processing * Revenue-sharing platforms * Transaction-based marketplaces **Volume and graduated tiers** Offer volume discounts that reward higher consumption. **Volume tiers** (customer pays only their tier rate): ```typescript { pricingModel: "tiered", tierType: "volume", usageMetricId: "api-calls-uuid" } // Tiers: // 0-100K calls: $0.10 per call + $20 flat fee // 100K+ calls: $0.07 per call + $100 flat fee // 150K calls → Tier 2: 150,000 × $0.07 + $100 = $10,600 ``` **Graduated tiers** (progressive like tax brackets): ```typescript { pricingModel: "tiered", tierType: "graduated", usageMetricId: "storage-gb-uuid" } // Tiers: // First 100 GB: $1.00 per GB // Next 400 GB: $0.75 per GB // 500+ GB: $0.50 per GB // 600 GB: // Tier 1: 100 × $1.00 = $100 // Tier 2: 400 × $0.75 = $300 // Tier 3: 100 × $0.50 = $50 // Total: $450 ``` **Real-world examples:** * **AWS S3**: Graduated pricing (first 50TB, next 450TB, etc.) * **Twilio**: Volume pricing for SMS based on monthly volume * **Google Cloud Storage**: Graduated tiers for different storage amounts **When to use:** * Encourage higher consumption with discounts * Reward loyal, high-volume customers * Create predictable pricing at scale **Packaged/stair-step pricing** Sell bundles of units at fixed prices. ```typescript { pricingModel: "packaged", unitAmount: 2500, // $25 per package packageSize: 1000, // 1,000 API calls per package usageMetricId: "api-calls-uuid" } // 3,200 calls → ceil(3,200 / 1,000) = 4 packages × $25 = $100 ``` **Real-world examples:** * **Mailchimp**: Email packages (10K emails for $X) * **Zapier**: Task packages (1K tasks for $X) * **Heroku**: Dyno hours in packaged blocks **When to use:** * Simplify pricing for customers * Encourage bulk purchasing * Reduce small transaction overhead ## Advanced usage patterns ### Included units and overages Give customers a base allocation, then charge for overages: ```typescript { pricingModel: "per_unit", unitAmount: 1000, // $0.10 per overage call includedUnits: 10000, // First 10K calls free usageMetricId: "api-calls-uuid" } ``` **Example flow:** 1. Customer's plan includes 10,000 API calls 2. They use 15,000 calls this month 3. Overage: 5,000 calls × $0.10 = $500 4. Invoice shows: "5,000 overage calls @ $0.10" ### Credit burndown Prepaid credits that customers consume over time: ```typescript { pricingModel: "per_unit", enableCreditBurndown: true, creditBurndownRate: 10, // 1 API call = 10 credits usageMetricId: "api-calls-uuid" } // Customer buys: $250 → 2,500 credits // Monthly usage: 300 calls = 3,000 credits needed // Credits available: 2,500 // Overage: 500 credits = 50 calls × $0.10 = $5 ``` **When to use:** * Encourage upfront commitment * Reduce billing friction * Provide budget predictability ### Minimum commitments Guarantee baseline revenue while charging for usage: ```typescript // Usage pricing { id: "api-usage-variant", pricingModel: "per_unit", unitAmount: 1000, // $0.10 per call usageMetricId: "api-calls-uuid" } // Minimum fee { name: "Monthly API Minimum", minimumAmount: 50000, // $500 minimum currency: "USD", billingInterval: "monthly" } // Calculation: // Usage: 3,500 calls × $0.10 = $350 // Minimum: $500 // True-up: $500 - $350 = $150 // Invoice: $350 (usage) + $150 (true-up) = $500 total ``` ## Common usage metrics by industry ### API Platforms * **API calls/requests**: Count of API invocations * **Data transfer**: GB of data sent/received * **Rate limit tier**: Requests per second/minute capacity ### Infrastructure/Cloud * **Compute hours**: Server/container runtime hours * **Storage GB**: Persistent storage consumed * **Bandwidth**: Data transfer in/out * **Concurrent resources**: Peak simultaneous instances ### Communications * **SMS sent**: Text messages delivered * **Voice minutes**: Phone call duration * **Email delivered**: Messages successfully sent * **Video minutes**: Video call duration ### AI/ML Services * **Model predictions**: Inference requests * **Training hours**: Model training compute time * **Tokens processed**: Text tokens (GPT-style) * **Image generations**: AI-generated images ### Payment Processing * **Transaction volume**: Dollar amount processed * **Transaction count**: Number of payments * **Payout volume**: Money transferred to sellers * **Fraud checks**: Risk analysis performed ## Usage tracking best practices ### Naming conventions * Use clear, descriptive keys: `api_calls`, `storage_gb`, `sms_sent` * Avoid generic names: `metric_1`, `usage`, `count` * Include units in labels: "API Calls (count)", "Storage (GB)" ### Data accuracy * **Idempotency**: Use unique event IDs to prevent double-counting * **Timestamps**: Always include event timestamp for accurate period assignment * **Validation**: Validate quantities before sending (no negative values) * **Reconciliation**: Compare internal metrics with Commet aggregations ### Customer transparency * **Real-time dashboards**: Show current usage vs limits * **Usage alerts**: Notify customers approaching limits * **Detailed invoices**: Break down usage by day/feature * **Historical reports**: Show usage trends over time ### Performance optimization * **Batch reporting**: Group events when real-time isn't critical * **Async tracking**: Don't block user requests on usage reporting * **Caching**: Cache aggregations for dashboards * **Sampling**: For ultra-high-volume metrics, consider sampling ## Troubleshooting usage-based billing | Issue | Cause | Solution | | ----------------------------------- | ----------------------------------- | -------------------------------------------- | | Usage not appearing on invoice | Events sent after period close | Ensure events sent before billing cycle ends | | Double-counted usage | No idempotency key | Add unique event IDs to prevent duplicates | | Incorrect aggregation | Wrong aggregation type (sum vs max) | Verify metric aggregation matches use case | | Usage spikes unexpectedly | Customer behavior change or bug | Set up usage alerts and anomaly detection | | Overage charges disputed | Customer unaware of limits | Implement proactive usage notifications | | Performance issues with high volume | Synchronous event tracking | Switch to async/batch usage reporting | # Seat Management (/docs/platform/features/seats/seats-overview) Seats are special events with unique handling. We manage them separately for better control. Use the SDK to create, remove, or adjust seat counts. Always know your active user count. ## Seat Types Create different seat types for roles or pricing tiers (paid vs free). **Create seat type**: Go to Seats → Types → + Add seat type ## Balance Tracking Monitor seat evolution over time, both total and per-customer. Useful for growth analysis without custom dashboards. ## Add Seats Increase seat count for a customer: ```typescript const result = await commet.seats.add({ customerId: 'cus_A1b2C3d4E5f6G7h8I9j0K1l2', seatType: 'admin', quantity: 5 }) console.log(`Added ${result.data.quantity} admin seats`) ``` ## Remove Seats Decrease seat count: ```typescript const result = await commet.seats.remove({ customerId: 'cus_A1b2C3d4E5f6G7h8I9j0K1l2', seatType: 'admin', quantity: 2 }) console.log(`Removed ${result.data.quantity} admin seats`) ``` ### Learn more

Common seat use cases

See seats-based product examples

[Learn more →](/docs/library/features/usage-events)

# Features (/docs/platform/features/plans-and-features/features) import { Callout } from 'fumadocs-ui/components/callout' import { Tabs, Tab } from 'fumadocs-ui/components/tabs' import { Steps, Step } from 'fumadocs-ui/components/steps' # Features Features define what customers can access and use within a Plan. They specify capabilities, usage limits, seat allocations, and pricing for overages. When you add features to a Plan, all customers assigned to that plan receive those features. The Platform section is designed for go-to-market, finance, and operations teams. If you need implementation details, go to the [Developer Library](/docs/library/quickstart). ## Quick start example Here's how features work in a typical SaaS plan: 1. **Define features**: Create features for capabilities like API calls, storage, or seats 2. **Add to plans**: Configure features in your Plans with included amounts and limits 3. **Automatic access**: When a customer is assigned a plan, they automatically get all plan features 4. **Track usage**: Monitor feature consumption in real-time through subscriptions Features make plans powerful by combining multiple capabilities into a single subscription package. ## Why features matter * **Define capabilities**: Specify exactly what customers can access in each plan * **Set limits**: Control usage with included amounts and overage pricing * **Track consumption**: Monitor how customers use each feature * **Flexible pricing**: Combine different feature types (boolean, metered, seats) in one plan * **Automatic enforcement**: Features are automatically tracked and billed based on usage ## Feature types Plans support three types of features, each serving different business needs: Boolean features are simple on/off capabilities. A customer either has access or they don't. | Aspect | Details | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **How it works** | On/off access to a capability | | **Examples** | • Single Sign-On (SSO) enabled
• Custom branding
• White-label options
• Priority support access
• Advanced analytics dashboard | | **Configuration** | • **Enabled**: Customer has access
• **Disabled**: Customer does not have access | | **Usage tracking** | No usage amounts or overage pricing—simply enabled or disabled based on the plan | Metered features track consumption and can include included amounts, overage pricing, or unlimited usage. | Aspect | Details | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **How it works** | Usage-based limits with optional overage pricing | | **Examples** | • API calls: 10,000 included, then $0.01 per call
• Storage: 100 GB included, then $0.10 per GB
• Compute hours: 50 hours included, then $2.00 per hour
• Email sends: 50,000 included, then $0.001 per email | | **Configuration options** | • **Included amount**: Free units included in the plan price
• **Unlimited**: No limits (use for premium plans)
• **Overage enabled**: Allow usage beyond included amount
• **Overage unit price**: Price per unit for overage usage | For detailed information about managing events, see the [Events Management documentation](../usage-metrics/events). Seat features allocate per-user licenses. Customers pay for each user who has access. | Aspect | Details | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **How it works** | Per-user licenses with included seats and optional overage | | **Examples** | • Editor seats: 5 included, then $10 per additional seat
• Admin seats: 2 included, then $25 per additional seat
• Team member seats: 10 included, then $5 per additional seat | | **Configuration options** | • **Included seats**: Number of seats included in the plan price
• **Unlimited**: No seat limits (use for enterprise plans)
• **Overage enabled**: Allow additional seats beyond included
• **Seat price**: Price per additional seat per billing period | For detailed information about managing seats, see the [Seat Management documentation](../seats/seats-overview). ## How to add features to a plan ### Navigate to plan configuration When creating or editing a Plan, go to the **Features** section. ### Add a feature Click **Add Feature** and select the feature you want to include. Features are created separately and can be reused across multiple plans. If the feature doesn't exist yet, you'll need to create it first. ### Configure feature settings Configure how the feature works in this specific plan: **For Boolean features:** * Enable or disable the feature **For Metered features:** * Set included amount (e.g., 10,000 API calls) * Choose unlimited or set limits * Enable overage and set unit price if applicable **For Seat features:** * Set included seat count (e.g., 5 editor seats) * Choose unlimited or set limits * Enable overage and set seat price if applicable ### Save and repeat Save the feature configuration and add additional features as needed. A single plan can include multiple features of different types. ## Feature configuration examples A Starter Plan with basic features: | Feature Type | Configuration | | ------------ | --------------------------------------------------- | | **Boolean** | SSO enabled ✗ | | **Metered** | API calls - 1,000 included, no overage (hard limit) | | **Metered** | Storage - 10 GB included, no overage (hard limit) | | **Seats** | Editor seats - 1 included, $15 per additional seat | A Pro Plan with multiple feature types: | Feature Type | Configuration | | ------------ | --------------------------------------------------- | | **Boolean** | SSO enabled ✓ | | **Boolean** | Custom branding ✓ | | **Metered** | API calls - 10,000 included, $0.01 per call overage | | **Metered** | Storage - 100 GB included, $0.10 per GB overage | | **Seats** | Editor seats - 5 included, $10 per additional seat | An Enterprise Plan with unlimited features: | Feature Type | Configuration | | ------------ | ------------------------ | | **Boolean** | SSO enabled ✓ | | **Boolean** | Custom branding ✓ | | **Boolean** | Priority support ✓ | | **Metered** | API calls - Unlimited | | **Metered** | Storage - Unlimited | | **Seats** | Editor seats - Unlimited | ## Feature access control Programmatic feature access checks and usage limits are now available! You can use our SDK and API to control and monitor feature access in your application. | Capability | What it does | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Check feature access** | Query if a customer has access to a specific feature (gate features in your app, verify plan includes feature) | | **Query usage and limits** | Check current usage, remaining capacity, seat counts, and overage status for metered features | | **Limit exceedance webhooks** | Receive real-time notifications when customers exceed limits (overage alerts, threshold warnings, seat capacity)
Coming soon | Use cases: Feature gating, usage dashboards, progress bars, automated enforcement, and customer notifications. **SDK & API feature checks are live!**\ Learn how to check and control feature access and usage in your application in the [Feature Access & Usage documentation](/docs/library/features/features). Webhook notifications for usage limit exceedance are coming soon. ## Common errors to avoid * **Setting limits too low**: Include enough free usage to provide value without overages * **Unclear feature names**: Use customer-friendly names, not internal codes * **Forgetting overage pricing**: If you allow overages, make sure pricing is configured * **Too many features**: Start with essential features and add more based on customer feedback * **Not tracking usage**: Ensure metered features are properly configured for tracking ## Editing features in plans You can modify feature configurations in a plan at any time: * **Change included amounts**: Update free usage limits * **Modify overage pricing**: Adjust prices for overage usage * **Add or remove features**: Include new features or remove unused ones * **Toggle boolean features**: Enable or disable capabilities **Important**: Changes to features in a plan only affect new subscriptions. Existing subscriptions keep their original feature configuration. If you need to update existing customers, you'll need to change their plan assignment. ## Related Resources * [Plans](./plans) - Learn how to create and configure plans * [Subscriptions](../subscriptions/subscriptions-overview) - Understand how features work in subscriptions * [Usage Metrics](../usage-metrics/metrics) - Track consumption for metered features * [Seat Management](../seats/seats-overview) - Manage seat-based features # Plans (/docs/platform/features/plans-and-features/plans) import { Callout } from 'fumadocs-ui/components/callout' import { Steps, Step } from 'fumadocs-ui/components/steps' # Plans Plans are pre-configured billing packages that combine pricing, features, and billing intervals. When you assign a Plan to a Customer, a Subscription is automatically created, making plan-based subscriptions the foundation of Commet's billing model. The Platform section is designed for go-to-market, finance, and operations teams. If you need implementation details, go to the [Developer Library](/docs/library/quickstart). ## Quick start example Here's how a typical SaaS company uses Plans: 1. **Create Plans**: Define your pricing tiers (Starter, Pro, Enterprise) with prices and features 2. **Assign Plan to Customer**: Select a customer and assign a plan—the subscription is created automatically 3. **Automatic billing**: Once active, Commet automatically generates recurring invoices each billing period 4. **Manage updates**: Change customer plans or update plan configurations as needed The billing engine handles the entire cycle: Plan creation → Plan assignment → Subscription creation → Checkout → Activation → Recurring billing. ## Why plans matter * **Consistency**: Standardize pricing across all customers using the same plan * **Automatic subscriptions**: Assigning a plan to a customer automatically creates their subscription * **Easy updates**: Modify plan features or pricing and all future subscriptions use the updated plan * **Public or private**: Control which plans appear on your pricing page vs. internal-only plans * **Scalability**: Create once, assign to many customers without manual configuration ## What are plans? Plans are templates that define everything a customer gets when they subscribe: | Component | Description | Example | | ---------------------- | ----------------------------------------------- | ---------------------------------------- | | **Name & Description** | Display information for customers and your team | "Pro Plan" - "Best for growing teams" | | **Prices** | Multiple pricing options by billing interval | $99/month, $990/year (save 17%) | | **Features** | What's included in the plan | API calls, storage, seats, feature flags | | **Trial Days** | Optional free trial period | 14 days free trial | | **Public Visibility** | Whether plan appears on pricing page | Public or private | Think of Plans as product packages. Once you create a Plan, you can assign it to multiple customers, and each assignment automatically creates a Subscription linked to that plan. Learn more about how Features work within Plans in the [Features documentation](./features). ## How to create a plan ### Navigate to Plans Go to **Plans** in the platform navigation and click **Create Plan**. ### Configure plan details Set up the basic plan information: * **Plan name**: Choose a clear, customer-facing name (e.g., "Starter", "Pro", "Enterprise") * **Description**: Add a brief description explaining the plan's value proposition * **Public or private**: * **Public**: Plan appears on your pricing page and can be selected by customers * **Private**: Plan only visible internally (useful for custom enterprise deals) ### Set pricing Add prices for different billing intervals: * **Monthly**: Recurring monthly billing * **Quarterly**: Recurring every 3 months (often with discount) * **Yearly**: Recurring annually (often with the best discount) For each billing interval: * Enter the price amount * Set one as the default (shown first when customers view plans) **Pricing strategy**: Many companies offer discounts for longer commitments. For example: $99/month, $270/quarter (save 9%), $990/year (save 17%). This encourages annual subscriptions while maintaining flexibility. ### Add features Configure what's included in the plan by adding features. Features define what customers can access: * **Boolean features**: On/off capabilities (e.g., SSO enabled, custom branding) * **Metered features**: Usage-based limits (e.g., 10,000 API calls included, then $0.01 per call) * **Seat features**: Per-user licenses (e.g., 5 editor seats included, $10 per additional seat) You can add multiple features of each type to a plan. For detailed information about configuring features, see the [Features documentation](./features). ### Configure trial period (optional) If you want to offer a free trial: * Set the number of trial days (e.g., 14 days) * Subscriptions created with this plan will start in "Trialing" status * Customers won't be charged until the trial period ends ### Save and publish Once configured, save your plan. If it's marked as public, it will appear on your pricing page. If it's private, only your team can assign it to customers. ## Plan structure ### Basic information | Field | Description | Example | | --------------- | ------------------------------------ | ------------------------ | | **Name** | Display name for the plan | "Pro Plan" | | **Description** | Brief explanation of plan value | "Best for growing teams" | | **Code** | Internal identifier (auto-generated) | "pro" | | **Public** | Whether plan appears on pricing page | Yes/No | | **Sort Order** | Display order on pricing page | 1, 2, 3... | ### Pricing Each plan can have multiple prices for different billing intervals: | Billing Interval | Description | Typical Use | | ---------------- | ------------------------- | ------------------------------------ | | **Monthly** | Recurring monthly billing | Default option, highest flexibility | | **Quarterly** | Recurring every 3 months | Small discount, quarterly commitment | | **Yearly** | Recurring annually | Best discount, annual commitment | When a customer is assigned a plan, they select which billing interval they want. The subscription will use this interval for all future billing cycles. ### Trial configuration | Setting | Description | Example | | ------------------ | ----------------------------------------- | ---------------------------------------- | | **Trial Days** | Number of free days before billing starts | 0 (no trial) to 365 | | **Trial Behavior** | How trial affects subscription status | Subscription starts in "Trialing" status | If a plan has trial days configured, all subscriptions created with that plan will automatically start in trial mode. ## How plans connect to subscriptions When you assign a Plan to a Customer: 1. **Subscription is created automatically** — No manual subscription creation needed 2. **Plan configuration is copied** — Subscription inherits all plan settings (pricing, features, trial) 3. **Billing interval is set** — Customer selects monthly, quarterly, or yearly at assignment 4. **Status is determined** — Subscription starts in the appropriate status: * **Trialing**: If plan has trial days * **Pending payment**: If payment is required * **Active**: If no payment or trial needed Once assigned, the subscription is independent—changes to the plan don't affect existing subscriptions, only new assignments. For detailed information about managing subscriptions created from plans, see the [Subscriptions documentation](../subscriptions/subscriptions-overview). ## Related Resources * [Features](./features) - Understand how features work within plans * [Subscriptions](../subscriptions/subscriptions-overview) - Learn how subscriptions are automatically created from plans * [Usage Metrics](../usage-metrics/metrics) - Track consumption for metered features * [Seat Management](../seats/seats-overview) - Manage seat-based features # Subscriptions (/docs/platform/features/subscriptions/subscriptions-overview) import { Callout } from 'fumadocs-ui/components/callout' import { Steps, Step } from 'fumadocs-ui/components/steps' # Subscription Management Subscriptions are automatically created when you assign a Plan to a Customer. They connect plans, customers, and billing cycles in an automated workflow that handles recurring billing, feature access, and usage tracking. The Platform section is designed for go-to-market, finance, and operations teams. If you need implementation details, go to the [Developer Library](/docs/library/quickstart). ## Quick start example Here's how subscriptions work with Commet's plan-first model: 1. **Create Plans**: Define your pricing tiers (Starter, Pro, Enterprise) with features and prices 2. **Assign Plan to Customer**: Select a customer and assign a plan—the subscription is created automatically 3. **Automatic billing**: Once active, Commet automatically generates recurring invoices each billing period 4. **Manage lifecycle**: Upgrade, downgrade, or cancel subscriptions as customer needs change The billing engine handles the entire cycle: Plan assignment → Subscription creation → Checkout → Activation → Recurring billing. ## Why subscriptions matter * **Automated recurring billing**: Once active, subscriptions automatically generate invoices each period without manual intervention * **Complete lifecycle control**: Manage states, cancellations, and renewals from a single place * **Full visibility**: Access invoice history, payments, and customer details in real time * **Plan-based simplicity**: Subscriptions inherit all configuration from plans, making management easier * **Automatic creation**: No manual subscription setup needed—just assign a plan to a customer ## Plan-first subscription model In Commet, subscriptions are not created manually from the platform interface. Instead, they are automatically created when you assign a Plan to a Customer. ### How it works **Create your Plans** with all pricing, features, and billing intervals configured **Assign a Plan to a Customer** — this automatically creates a Subscription **The Subscription starts** in the appropriate status based on payment and trial settings This plan-first approach ensures: * **Consistency**: All customers on the same plan get the same configuration * **Simplicity**: No need to manually configure each subscription * **Scalability**: Easily manage hundreds or thousands of subscriptions * **Updates**: Modify plans and future assignments use the updated configuration Learn more about creating and managing Plans in the [Plans documentation](../plans-and-features/plans). ## How subscriptions are created ### Select or create customer Navigate to **Customers** in the platform and select the customer you want to assign a plan to. If the customer doesn't exist yet, you can create them directly from the customer management section. **Important**: The customer's email is used as the delivery address for the payment link and cannot be modified in the checkout. Make sure to use the correct email from the start. ### Assign a plan From the customer detail page, click **Assign Plan** or **Change Plan**. You'll see all available plans: * **Public plans**: Plans visible on your pricing page * **Private plans**: Internal plans not shown publicly (useful for enterprise deals) Select the plan you want to assign. You can also choose: * **Billing interval**: Monthly, quarterly, or yearly (if the plan supports multiple intervals) * **Initial seats**: For plans with seat-based features, set the starting seat count * **Skip trial**: Optionally skip the trial period if the plan has one configured ### Subscription is created automatically When you confirm the plan assignment, Commet automatically: * Creates a Subscription for the customer * Links the subscription to the selected plan * Sets the billing interval and initial configuration * Generates a checkout link if payment is required The subscription status depends on the plan configuration: * **Trialing**: If the plan has trial days configured * **Pending payment**: If payment is required to activate * **Active**: If no payment or trial is needed ## Subscription lifecycle Subscriptions go through different states during their lifetime: | State | Description | When it occurs | | ----------------- | ------------------------------------------ | ----------------------------------------------------- | | `Draft` | Subscription created but not activated | When created programmatically for review | | `Trialing` | Customer in free trial period | When plan has trial days and trial hasn't ended | | `Pending payment` | Customer received checkout but hasn't paid | Immediately after plan assignment if payment required | | `Active` | Subscription is billing normally | After trial ends or payment is completed | | `Paused` | Temporarily paused (no billing) | When manually paused by operations team | | `Past due` | Payment failed, in grace period | When payment method fails | | `Canceled` | Canceled, no longer billing | When customer cancels or subscription ends | | `Expired` | Reached end date | When subscription reaches scheduled end | ## Subscription details Each subscription includes complete information to manage the billing cycle: ### Current plan information * **Plan name**: See which plan the customer is subscribed to * **Billing interval**: Monthly, quarterly, or yearly * **Plan features**: View all features included in the plan * **Trial status**: Check if subscription is in trial period ### Billing information * **Current period**: Start and end dates of the current billing cycle * **Days remaining**: How many days until the next invoice * **Next invoice date**: When the next recurring invoice will be generated * **Amount**: Current plan price for the selected billing interval ### Feature usage For plans with metered or seat-based features: * **Current usage**: Track consumption in real-time * **Included limits**: See what's included in the plan * **Overage**: Monitor usage beyond included amounts * **Seat counts**: Current seat allocation per seat type Learn more about how features work in plans in the [Features documentation](../plans-and-features/features). ### Checkout link * **View current link**: Access the payment link generated for the customer * **Regenerate link**: If the checkout expired or you need a new link, you can regenerate it (only available if the subscription is not active) * **Delivery to customer**: The checkout link is sent automatically to the customer's email. If you're using the SDK, you can also integrate the link directly into your onboarding flow. ### Generated invoices * **Complete history**: View all invoices generated for this subscription * **Automatic billing**: Each billing period automatically generates a new invoice * **Payment details**: Review payment status, due dates, and payment methods ### Customer information * **Contact data**: Quickly access the associated customer information * **Subscription history**: View all active and historical subscriptions for the customer * **Billing configuration**: Review currency, payment terms, and billing address ## Managing subscriptions ### Change plan (upgrade/downgrade) Navigate to the customer detail page Click **Change Plan** on the active subscription Select the new plan Commet automatically handles proration: * Credits unused time from the current plan * Charges for the new plan going forward * Adjusts the billing cycle accordingly **Automatic proration**: Commet calculates credits and charges automatically when changing plans. The customer is charged or credited based on the time remaining in the billing period. ### Cancel subscription Navigate to the customer detail page Click **Cancel Subscription** on the active subscription Optionally provide a cancellation reason Choose when cancellation takes effect: * **Immediately**: Stops billing right away * **End of period**: Continues billing until current period ends Canceled subscriptions remain visible for historical tracking but no longer generate invoices. ### Regenerate checkout link If a customer hasn't completed payment and the checkout link expired: Navigate to the subscription details Click **Regenerate Checkout Link** Send the new link to the customer This is more efficient than reassigning the plan or creating a new subscription. ## SDK integration All the steps described above can be performed programmatically through our SDK. This is the recommended way to integrate Commet directly into your application. Subscription lifecycle sequence diagram **For in-app integrations**: If you're building an integration within your application, use the SDK instead of the platform interface. This allows you to completely automate the subscription flow and keep everything synchronized with your system. ### Advantages of using the SDK * **Complete automation**: Assign plans and manage subscriptions directly from your code without manual intervention * **Real-time synchronization**: Keep your data synchronized with Commet automatically * **Improved user experience**: Integrate the checkout directly into your application without redirecting to external pages * **Scalability**: Manage thousands of subscriptions programmatically without interface limitations ### Typical SDK flow **List available plans**: Use `commet.plans.list()` to show customers available options **Assign plan**: Call `commet.subscriptions.create()` with a `planCode` to create the subscription automatically **Get checkout**: Access the checkout link from the subscription response **Monitor usage**: Track feature usage and seat counts through the subscription details **Manage changes**: Upgrade, downgrade, or cancel through the SDK For complete code examples and full API documentation, visit the [Developer Library](/docs/library/features/subscriptions). ## Related Resources * [Plans](../plans-and-features/plans) - Learn how to create and configure plans * [Features](../plans-and-features/features) - Understand how features work in plans * [Usage Metrics](../usage-metrics/metrics) - Track consumption for metered features * [Seat Management](../seats/seats-overview) - Manage seat-based features # Usage Events (/docs/platform/features/usage-metrics/events) ## Basic Usage Track user activity and bill for it. Common use cases: * **Token usage** - Measure API token consumption * **Conversation count** - Track chat/message volume * **Payment tracking** - Count transaction events Seats use events too, but are handled differently. See the [Seat Management](/library/features/seat-management) section. Send a single usage event: ```typescript const result = await commet.usage.create({ eventType: 'api_call', customerId: 'cus_A1b2C3d4E5f6G7h8I9j0K1l2', quantity: 1, }) console.log('Event tracked:', result.data.id) ``` ## Event Types Create event types in the Commet dashboard first. This makes them available in our SDK for easier integration. ### Learn more

Usage events library

How to integrate events with our SDK

[Learn more →](/docs/library/features/usage-events)

# Metrics (/docs/platform/features/usage-metrics/metrics) ## Define Usage Metric Create a usage metric that tracks specific customer behavior: ```json { "id": "api-calls-metric-uuid", "name": "API Calls", "key": "api_calls", "aggregationType": "sum", "unitLabel": "calls" } ``` ## Aggregation Types * **Sum** - Total units consumed (API calls, storage GB, compute hours) * **Max** - Peak concurrent usage (max simultaneous connections, peak compute) * **Unique** - Distinct count (monthly active users, unique API keys used) * **Count** - Number of events (transactions, deployments, builds) ## Create Metrics Click "Create Metric" and configure: * **Event type** - Which events to track * **Aggregation type** - How to group them (sum, count, etc.) * **Metadata filters** - Optional conditions to filter specific events ## View Metrics Analyze metrics over time and filter by customer. Get visibility into how users consume your platform. ### Learn more

Common Use Cases

See usage-based product examples

[Learn more →](/docs/library/features/usage-events)