What Billing and Credit System Does OpenSEO Use? Autumn Integration Explained

OpenSEO uses Autumn as its core billing and credit-management platform, with lazy-loaded SDK access, feature-based balance checks, and automated usage tracking.

The every-app/open-seo repository implements a pay-as-you-go pricing model powered by Autumn's API. This article breaks down how the codebase handles customer provisioning, credit balance queries, and usage deductions—complete with the actual implementation files and runnable TypeScript examples.

How OpenSEO's Autumn Billing System Works

The Autumn SDK Facade

OpenSEO loads the Autumn SDK lazily through a dedicated façade module at src/server/billing/autumn.ts. This keeps the warm isolate small (≈ 450 KB) while centralizing all billing interactions.

The module exports a singleton autumn object that wraps three core operations:

• autumn.check() – Query feature balances
• autumn.track() – Record usage deductions
• autumn.customers.getOrCreate() – Provision customer accounts

// src/server/billing/autumn.ts pattern
import { autumn } from "@/server/billing/autumn";

// All billing operations route through this object
const balance = await autumn.check({ customerId, featureId });

Credit-to-USD Conversion in OpenSEO

Raw credits from the DataForSEO provider are converted to USD using the autumnSeoDataCreditsToUsd helper in src/shared/billing.ts. This function applies a constant rate multiplier to normalize credit values for display and accounting.

import { autumnSeoDataCreditsToUsd } from "@/shared/billing";

// Convert Autumn balance to displayable USD amount
const usdAmount = autumnSeoDataCreditsToUsd(autumnCredits);

The hosted OpenSEO service adds a 28% markup on DataForSEO API costs, but the underlying credit accounting remains fully managed by Autumn.

Checking Customer Subscription Status

The customerHasPaidPlan Gate

Premium feature access is controlled through src/server/billing/subscription.ts. The customerHasPaidPlan function queries the SEO Data Balance feature via autumn.check to determine eligibility.

// 1️⃣ Gate a premium endpoint with subscription check
import { customerHasPaidPlan } from "@/server/billing/subscription";

export async function handler(context) {
  const hasPlan = await customerHasPaidPlan(context);
  if (!hasPlan) throw new Error("Upgrade required");
  // …premium logic executes here
}

This pattern ensures consistent enforcement across all paid features without duplicating balance logic.

Manual Balance Queries

For granular control, call autumn.check directly with the SEO Data Balance feature ID:

// 2️⃣ Query specific credit balance for a feature
import { autumn } from "@/server/billing/autumn";

async function getSeoDataBalance(customerId: string) {
  const result = await autumn.check({
    customerId,
    featureId: "AUTUMN_SEO_DATA_BALANCE_FEATURE_ID",
  });
  
  // Convert to USD for client display
  const usd = autumnSeoDataCreditsToUsd(result.balance);
  
  return { credits: result.balance, usd };
}

Tracking Usage and Deducting Credits

The autumn.track Method with Retry Protection

Usage deductions use autumn.track with configurable retry options to prevent double-charging. The AUTUMN_TRACK_RETRY_OPTIONS constant from the façade module provides safe defaults.

// 3️⃣ Deduct credits after a DataForSEO API call
import { autumn, AUTUMN_TRACK_RETRY_OPTIONS } from "@/server/billing/autumn";

async function deductUsage(customerId: string, amountCredits: number) {
  await autumn.track(
    {
      customerId,
      amount: amountCredits,
      description: "Keyword-research request",
    },
    AUTUMN_TRACK_RETRY_OPTIONS,
  );
}

The retry options ensure idempotent tracking—critical for preventing duplicate charges during network failures or timeouts.

Autumn Billing Architecture Summary

Component	File Path	Responsibility
SDK façade	src/server/billing/autumn.ts	Lazy initialization, retry configuration, autumn object export
Subscription logic	src/server/billing/subscription.ts	customerHasPaidPlan, feature gating
Currency conversion	src/shared/billing.ts	autumnSeoDataCreditsToUsd helper
Pricing model	README.md	Pay-as-you-go documentation, 28% markup disclosure

Key Files for OpenSEO Billing Integration

Understanding these three files unlocks the full billing flow:

• src/server/billing/autumn.ts – Single source of truth for Autumn SDK access
• src/server/billing/subscription.ts – Business-level subscription state
• src/shared/billing.ts – Credit normalization utilities

Summary

• Autumn is the dedicated billing and credit system for OpenSEO, handling customer identity, balance queries, and usage tracking.
• The SDK is lazily loaded via src/server/billing/autumn.ts to optimize cold-start performance.
• Feature-based billing uses autumn.check with specific feature IDs like "SEO Data Balance."
• Credit conversions flow through autumnSeoDataCreditsToUsd for USD display.
• Retry-safe deductions use autumn.track with AUTUMN_TRACK_RETRY_OPTIONS to prevent duplicate charges.

Frequently Asked Questions

What external service does OpenSEO use for billing?

OpenSEO uses Autumn as its billing and credit-management platform. According to the every-app/open-seo source code, all customer provisioning, balance checks, and usage tracking route through the Autumn API via a lazy-loaded SDK façade.

How does OpenSEO convert DataForSEO credits to USD?

The autumnSeoDataCreditsToUsd function in src/shared/billing.ts applies a constant rate multiplier to convert raw DataForSEO credits into USD values. The hosted OpenSEO service then adds a 28% markup on top of this base cost.

What prevents double-charging when tracking usage?

The autumn.track method accepts AUTUMN_TRACK_RETRY_OPTIONS from src/server/billing/autumn.ts, which configures idempotent retry behavior. This ensures that network failures or timeouts don't result in duplicate credit deductions.

Where is subscription status checked in the codebase?

Premium feature gating uses customerHasPaidPlan from src/server/billing/subscription.ts. This function internally calls autumn.check for the SEO Data Balance feature and is imported by API route handlers to enforce paid plan requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}