# Billing Classification System for DataForSEO API Calls in OpenSEO: How Usage Tracking Works

> Discover OpenSEO's billing classification system for DataForSEO API calls. Learn how requests are mapped to features, failures detected, and markup pricing applied to raw costs.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-05

---

**OpenSEO classifies every DataForSEO API call through a three-layer system that maps requests to credit features, detects billing-related failures, and applies markup pricing to raw costs.**

The `every-app/open-seo` repository implements a sophisticated billing classification system to manage DataForSEO API usage across its SEO platform. This system ensures accurate credit tracking, graceful handling of insufficient balance scenarios, and proper cost conversion for end-user billing. Understanding how OpenSEO categorizes and prices these third-party API calls is essential for developers extending the platform or debugging usage-related issues.

## Credit-Feature Mapping for Usage Tracking

OpenSEO tracks every DataForSEO request by assigning it to a specific product-level **credit feature**. This allows the platform to meter consumption accurately across different SEO modules like keyword research, backlinks, and rank tracking.

The classification logic resides in [`src/shared/billing-credit-features.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing-credit-features.ts). The function `mapDataforseoPathToCreditFeature` parses the DataForSEO response path array to determine the appropriate `CreditFeature` enum value.

```typescript
import { mapDataforseoPathToCreditFeature } from "@/shared/billing-credit-features";

const path = ["v3", "dataforseo_labs", "google", "related_keywords", "live"];
const feature = mapDataforseoPathToCreditFeature(path);
// feature === "keyword_research"

```

The function distinguishes between modules such as `backlinks`, `serp`, `ai_optimization`, and `dataforseo_labs`, ensuring that each API call consumes the correct type of usage credit defined in the platform's billing model.

## Billing-Error Classification for Insufficient Funds

When a DataForSEO account depletes its balance, OpenSEO converts raw SDK errors into typed `AppError` instances that the application can handle uniformly. This **billing-error classification** prevents cryptic failure messages and enables graceful degradation.

The classifier is implemented in [`src/server/lib/dataforseoBillingClassification.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseoBillingClassification.ts) via the `createDataforseoBillingClassifier` factory function. It detects billing issues through two complementary checks:

- **HTTP status codes**: The set `{402, 40200, 40210}` (DataForSEO uses 402 for "payment required")
- **Error message substrings**: `["insufficient funds", "balance is too low", "payment required", "billing", "balance", "problem billing", "recharged"]`

If either test matches and the request path contains the configured prefix, the classifier returns an `AppError` with a custom `ErrorCode` and user-friendly message.

```typescript
import { createDataforseoBillingClassifier } from "@/server/lib/dataforseoBillingClassification";

const backlinksBillingClassifier = createDataforseoBillingClassifier({
  pathPrefix: "/backlinks",
  billingIssueCode: "BALANCE_DEPLETED",
  billingIssueMessage: "Your DataForSEO balance is empty – please top-up.",
});

try {
  const data = await dataforseoClient.backlinks.summary({ /*…*/ });
} catch (err) {
  const appErr = backlinksBillingClassifier(err.status, err.details, err.path);
  if (appErr) {
    console.error(appErr.message);
  } else {
    throw err;
  }
}

```

## Cost Conversion and Markup Calculation

Raw DataForSEO costs undergo transformation before appearing on customer invoices. The `applyBillingMarkupUsd` function in [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) applies a standard markup to third-party API costs.

The system multiplies the raw USD cost by a markup factor of **1.28**, then rounds the result to five decimal places using `roundUsdForBilling`. This ensures precise accounting while accounting for platform overhead.

```typescript
import { applyBillingMarkupUsd } from "@/shared/billing";

const rawUsd = 0.075;
const billedUsd = applyBillingMarkupUsd(rawUsd);
// billedUsd ≈ 0.096 (0.075 × 1.28)

```

## Integration Within the DataForSEO Client

These classification layers converge in [`src/server/lib/dataforseo/client.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/client.ts), specifically within the `meterDataforseoCall` function. Each outgoing request passes through the credit-feature mapper to determine billing category, while responses route through the billing-error classifier to catch insufficient balance scenarios before they propagate to users.

According to the OpenSEO source code, this unified approach ensures that credit consumption is tracked accurately, billing failures are handled gracefully, and customers see consistent pricing regardless of which DataForSEO endpoint they access.

## Summary

- **Credit-feature mapping** assigns each DataForSEO API call to a specific usage category (keyword research, backlinks, etc.) via `mapDataforseoPathToCreditFeature` in [`src/shared/billing-credit-features.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing-credit-features.ts).
- **Billing-error classification** detects depleted account balances by checking HTTP status codes 402/40200/40210 and specific error message substrings through `createDataforseoBillingClassifier`.
- **Cost markup** applies a 1.28 multiplier to raw DataForSEO costs using `applyBillingMarkupUsd` in [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts).
- The classification system integrates at the client level in [`src/server/lib/dataforseo/client.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/client.ts) to provide seamless metering and error handling.

## Frequently Asked Questions

### What happens when a DataForSEO account runs out of credits?

OpenSEO detects the depleted balance through the billing-error classifier, which monitors for HTTP 402 status codes and error messages containing phrases like "insufficient funds" or "balance is too low". When triggered, the system converts the raw error into a typed `AppError` with a user-friendly message, allowing the UI to prompt users to top up their balance rather than displaying a cryptic API failure.

### How does OpenSEO determine which credit feature to charge for an API call?

The platform uses the `mapDataforseoPathToCreditFeature` function to parse the DataForSEO response path array. By analyzing segments like `dataforseo_labs`, `backlinks`, or `serp`, the function returns the appropriate `CreditFeature` enum value that corresponds to the specific SEO module being accessed, ensuring accurate usage tracking across different product features.

### What markup percentage does OpenSEO apply to DataForSEO costs?

OpenSEO applies a 28% markup to raw DataForSEO costs, multiplying the vendor's USD amount by **1.28** before billing the end user. The `applyBillingMarkupUsd` function in [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) handles this calculation and rounds the result to five decimal places to ensure precise financial reporting.

### Where is the billing classification logic implemented in the OpenSEO codebase?

The billing classification system spans three primary files: [`src/shared/billing-credit-features.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing-credit-features.ts) for credit feature mapping, [`src/server/lib/dataforseoBillingClassification.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseoBillingClassification.ts) for error classification, and [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) for cost markup calculations. These utilities are orchestrated within [`src/server/lib/dataforseo/client.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/client.ts) to provide comprehensive billing management for all DataForSEO API interactions.