Rate limits + tokens

Two limits: tokens per month (your plan's allowance) and calls per minute (your throttle).

Two limits

Every plan has:

Monthly token quota — total tokens you can spend in a billing cycle
Per-minute throttle — maximum calls per minute

Hit either and you get a 429 response with a Retry-After header.

Plan tiers

Plan	Price	Tokens / month	Calls / min (without force_refresh)	Calls / min (force_refresh=true)
Free	$0	1,000	5	5
Starter	$49/mo	864,000	500	60
Growth	$119/mo	2,592,000	60	60
Pro	$429/mo	10,800,000	100	100
Business	$819/mo	21,600,000	100	100
Scale	$1,399/mo	43,200,000	100	100
Fleet	$2,339/mo	86,400,000	100	100
Volume	$3,279/mo	129,600,000	100	100
Enterprise	$4,209/mo	172,800,000	100	100

The per-minute limit depends on your plan and whether the request uses force_refresh=true. Monthly tokens are accounted for separately.

Token costs per call

Call	Tokens
Base lookup (30/60/90/180-day price aggregates + Bucket-1 facts + computed marketplace fees)	1
+ `include_cross_retailer` (cached cells for all retailers we have for this UPC, read-only)	+2
+ `include_seller_context` (live restriction + WFS eligibility state)	+3
+ `include_offers_reviews` (live sellers + review summary + top 5 reviews)	+5
+ `include_offers_history` (historical marketplace offers — price/seller archive, Walmart)	+5
+ `include_price_series` (raw day-by-day price bars — the aggregates themselves are free, Walmart)	+10
`?retailer=<r>` (anchor response to one retailer)	1
`?retailer=<r>&force_refresh=true` (anchor + fresh scrape — only way to force fresh data)	1

Marketplace fees (referral_fee_usd, wfs_fee_usd) are computed from public rate cards and ride FREE on the base call — same model as Keepa's referralFeePercentage. include_seller_context pays only for the live-state fields (is_restricted, WFS eligibility) that require a richer upstream pull.

How throttle works

The API checks calls per minute against the applicable limit above. Use the response headers to check your remaining allowance and back off when you receive a 429 response.

Response headers

X-RateLimit-Tokens-Remaining: 998     # tokens left this billing cycle
X-RateLimit-Throttle-Limit: 60        # calls per minute
X-RateLimit-Throttle-Remaining: 47    # calls remaining now
X-RateLimit-Reset: 2026-06-01T00:00Z  # when monthly quota resets

What happens when you exceed

Both limits return 429 Too Many Requests. Different Retry-After semantics:

Throttle — Retry-After is a few seconds. Back off and retry.
Monthly quota — Retry-After is the next renewal date. Either upgrade or wait.

Quota-exceeded calls do NOT auto-charge overage; we fail closed. If you want to pay for spillover, contact sales or upgrade plan.

Best practices

Check X-RateLimit-Tokens-Remaining after each call to track burn rate
For batch jobs, pace calls below the applicable per-minute limit to leave headroom for ad-hoc calls
Cache responses client-side when appropriate (titles, brands, images rarely change)
For routine lookups, the base call (1 token) already includes price history, stats, Bucket-1 facts, and computed marketplace fees — only add include_offers_reviews=true when you need live sellers or full review data
Reseller workflows usually want include_cross_retailer=true&include_seller_context=true (6 tokens) — the full per-retailer + restriction + WFS picture