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

> Discover OpenSEO's billing and credit system, Autumn. Learn how it manages usage, balances, and provides SDK access for seamless integration.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: internals
- Published: 2026-08-09

---

**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`](https://github.com/every-app/open-seo/blob/main/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

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)**. This function applies a constant rate multiplier to normalize credit values for display and accounting.

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/server/billing/subscription.ts)**. The `customerHasPaidPlan` function queries the **SEO Data Balance** feature via `autumn.check` to determine eligibility.

```typescript
// 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:

```typescript
// 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.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/src/server/billing/autumn.ts) | Lazy initialization, retry configuration, `autumn` object export |
| Subscription logic | [`src/server/billing/subscription.ts`](https://github.com/every-app/open-seo/blob/main/src/server/billing/subscription.ts) | `customerHasPaidPlan`, feature gating |
| Currency conversion | [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) | `autumnSeoDataCreditsToUsd` helper |
| Pricing model | [`README.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/billing/autumn.ts)** – Single source of truth for Autumn SDK access
- **[`src/server/billing/subscription.ts`](https://github.com/every-app/open-seo/blob/main/src/server/billing/subscription.ts)** – Business-level subscription state
- **[`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.