{
  "object": "doc",
  "title": "How are Cartroute credits counted?",
  "description": "What each call costs, when you are not charged, free credits and plans.",
  "section": "Getting started",
  "url": "https://cart-route.com/docs/credits",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/authentication",
  "next": "https://cart-route.com/docs/sandbox",
  "text": "One credit is spent per successful search, product, price-history or coupon call. Reference and account endpoints are free. Failed calls cost nothing. New accounts get 100 credits immediately and 100 more when the email address is confirmed; paid plans add 5,000 or 50,000 credits a month.\n\n## What does each call cost?\n\n| Operation | REST | MCP tool | Credits |\n\n| Search all retailers | `GET/POST /search` | `search_products` | 1 |\n\n| Product with every offer | `GET /products/{id}` | `get_product` | 1 |\n\n| Price history | `GET /products/{id}/price-history` | `get_price_history` | 1 |\n\n| Coupons | `GET /coupons` | `find_coupons` | 1 |\n\n| Retailers, categories | `GET /retailers`, `/categories` | `list_retailers`, `list_categories` | 0 |\n\n| Balance, ledger | `GET /account`, `/usage` | `get_account` | 0 |\n\n| Web search on this site | `/search` page, logged in | n/a | 1 |\n\n## When is a call not charged?\n\n- Validation errors (`422`): the input is checked before anything is charged.\n\n- Authentication and suspension errors (`401`, `403`).\n\n- Rate-limit responses (`429`) and server errors (`5xx`).\n\n- A repeat of a call with the same `Idempotency-Key` within 24 hours (see [retries](https://cart-route.com/docs/idempotency)).\n\nA search that matches nothing is charged. \"No product matches\" is an answer the call paid to learn, and the response says so in `notes`.\n\n## How do I see my balance?\n\nEvery metered response includes `credits.charged` and `credits.remaining`, repeated in the `X-Credits-Charged` and `X-Credits-Remaining` headers. `GET /api/v1/account` returns the balance and a `low_balance` flag (below 20); `GET /api/v1/usage` returns the ledger. The dashboard shows a 30-day usage chart.\n\n## What happens at zero?\n\nMetered calls return `402` with `code: \"insufficient_credits\"`, `credits_remaining`, `top_up_url` and, if the email is still unconfirmed, `verify_email_bonus`. An agent should stop and tell its user rather than retry.\n\n## Do free credits expire?\n\nNo. Signup and verification credits stay on the account until used. Plan credits are granted monthly.\n\n## What are the plans?\n\n| Plan | Price | Credits | Extra 1,000 | Rate limit |\n\n| Free | $0 | 200 once | n/a | 120/min |\n\n| Builder | $29/mo | 5,000/mo | $6 | 120/min |\n\n| Scale | $199/mo | 50,000/mo | $4 | 600/min |\n\n| Enterprise | Custom | Volume | Custom | Custom |\n\nSee [pricing](https://cart-route.com/pricing), or email [sales@cart-route.com](mailto:sales@cart-route.com) for Enterprise."
}