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

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. The function mapDataforseoPathToCreditFeature parses the DataForSEO response path array to determine the appropriate CreditFeature enum value.

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 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.

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 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.

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, 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.
• 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.
• The classification system integrates at the client level in 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 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 for credit feature mapping, src/server/lib/dataforseoBillingClassification.ts for error classification, and src/shared/billing.ts for cost markup calculations. These utilities are orchestrated within src/server/lib/dataforseo/client.ts to provide comprehensive billing management for all DataForSEO API interactions.

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