Credits & billing

Every successful API-key request consumes monthly API credits. This guide explains the quota, when it resets, what counts as a billable request, and how to monitor usage.

The quota#

When the quota is reached, every subsequent request returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "success": false,
  "error": "Monthly credit limit reached (20000). Resets next month.",
  "credits": { "used": 20000, "limit": 20000, "remaining": 0 }
}

The counter resets automatically at the start of the next calendar month — no action needed.

What counts (and what doesn't)#

Every metered programmatic call attempts 1 credit before the main work runs. If the server hits an uncaught error after charging, the credit is refunded — you are not charged for that failure.

Metered routes include:

• All /api/v1/tiktok-shop/* endpoints.
• GET /api/v1/adlibrary.
• POST /api/v1/magic-ai.
• GET /api/v1/store-tracker, POST /api/v1/store-explorer.
• GET /api/v1/brands.

Un-versioned /api/adlibrary, /api/store-tracker, and /api/store-explorer are still accepted as aliases (same metering). /api/magic-ai and /api/brands are dashboard routes — for an API key use /api/v1/magic-ai and /api/v1/brands.

Before any credit is taken, these responses return without charging (and they do not count toward the per-minute rate limit):

• 401 Unauthorized — missing or invalid key.
• 403 — API access not enabled for the account.

Successful responses and most 429 rows are logged and count toward the 60/min window (see Rate limits).

Dashboard vs API#

The browser app may apply different metering than raw API-key calls. For integrations, assume 1 credit per successful metered request unless your contract states otherwise.

Monitoring credit usage#

Programmatic#

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

Returns the same { used, limit, remaining } shape that the 429 body carries. Costs 1 credit (yes, checking the balance charges a credit; cache it client-side).

Dashboard#

While logged in:

• GET /api — visual credits widget + 14-day usage chart + recent request log.
• GET /api/usage — JSON: { usage: [{ day, requests }, …], credits: { used, limit, remaining } }.
• GET /api/logs?page=N — paginated 50-per-page request log with status codes and IPs.

These three are session-only (cookies). They do not consume credits.

MCP and credits#

Model Context Protocol uses the same monthly pool (20,000). Each successful MCP tools/call charges 1 credit — including tools like check_credits. initialize, tools/list, ping, etc. do not charge.

MCP tool traffic has its own per-minute burst cap (see MCP); it does not replace this guide’s REST rate-limit story for /api/*.

Capacity planning#

For sustained ETL or backfill workloads, design around the per-day capacity, not the per-minute one. The rate limit caps burst (60/min); the credit quota caps volume (20,000/month).

Strategies that stretch your credits#

• Batch with POST JSON. Big filter sets in a single request beat many narrow ones.
• Cache stable lookups. Categories hierarchies, country lists, filter presets — fetch once a day at most.
• Use count before explore when you only need a number.
• Don't poll credits aggressively — it costs 1 credit each call. Track usage client-side from your own response counter, and re-sync from /api/v1/tiktok-shop/credits once an hour.

Reset behavior#

Usage resets at the start of each calendar month (UTC) on the server. The first metered request in a new month picks up a fresh counter automatically.

What about plan changes?#

• Upgrade mid-month: your existing credit counter keeps ticking; the limit stays at 20,000 (the quota is per-user, not per-tier).
• Loss of API access: Metered calls return 403 until access is restored; prior usage counters typically carry over if you re-enable access in the same period—confirm in the dashboard.
• Higher-volume needs: contact support to discuss a custom limit.