Krediler ve faturalandırma

Every successful API-key call through the metered proxy charges 1 credit from the monthly programmatic API pool (plus optional add-ons).

Plan-based monthly limit#

Usage resets when the calendar month changes (server Y-m). Purchased add-on packs sit in addon_remaining and are drawn after the monthly allowance is exhausted.

Charge and refund#

The proxy charges 1 credit before the handler runs. On an uncaught exception the credit is refunded. Auth failures (401 / 403 plan gate) and rate-limit / credit-exhaustion 429s do not consume a credit. Soft handler failures that return an error JSON without throwing keep the charged credit.

Metered routes#

• Tümü /api/v1/tiktok-shop/*
• GET /api/v1/adlibrary, GET /api/v1/pinterest-ads, GET /api/v1/google-ads
• POST /api/v1/magic-ai
• POST /api/v1/landers/explore
• GET /api/v1/store-tracker, POST /api/v1/store-explorer, POST /api/v1/store-explorer/visual-search
• GET /api/v1/markalar ve /api/v1/brands/* (tracker tabs, boards/folders, follow/unfollow, digest prefs)
• GET/POST /api/v1/notifications/* (product inbox)
• GET /api/v1/store/google-ads ve /api/v1/store/google-ads/* (store-scoped Google Ads)
• GET /api/v1/landers/favorites, POST /api/v1/landers/favorites/toggle
• GET/POST /api/v1/saved-ads/* (saved ads library)
• POST /api/v1/trends/* (Exploding Topics search, detail, autocomplete)
• GET /api/v1/credits (probe — also costs 1)
• Ad transcript helpers under /api/v1/ad-transcript*

Takma adlar: /api/adlibrary, /api/mağaza-izleyici, /api/mağaza-keşfi (same metering). Use /api/v1/magic-ai, /api/v1/brands/*ve /api/v1/notifications/* with an API key — bare /api/magic-ai ve /api/markalar/* (olmadan) v1) are legacy session paths.

Probe balance#

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

{
  "success": true,
  "credits": {
    "used": 142,
    "limit": 20000,
    "remaining": 19858,
    "addon_remaining": 500,
    "total_remaining": 20358
  }
}

total_remaining = remaining + addon_remaining.

Not the same pool#

GET /api/v1/tiktok-shop/credits returns TikTok Shop arama credits:

{ "success": true, "credits_remaining": null, "credits_unlimited": true }

On Basic plans credits_remaining is a non-negative integer and credits_unlimited is false. That is değil the programmatic monthly pool above. Prefer GET /api/v1/credits to monitor API metering.

Credit exhaustion (429)#

{
  "success": false,
  "error": "No API credits remaining. Buy an add-on pack or wait until next monthly reset.",
  "credits": {
    "used": 20000,
    "limit": 20000,
    "remaining": 0,
    "addon_remaining": 0,
    "total_remaining": 0
  },
  "purchase": { "url": "https://…/checkout-api-credits?credits=…" }
}

Presence of krediler distinguishes this from rate-limit 429 (Hatalar).

Dashboard (session, free)#

Oturum açılmışken: /api, GET /api/kullanım, GET /api/logs — no API-key credit charge.

Tips#

• Don’t poll /api/v1/credits every request — it costs 1 credit.
• Prefer one filtered explore over many narrow calls.
• MCP araçlar/çağrı uses the same monthly pool (1 credit per successful tool call).

Related#