# Credits, billing and refunds

## Credits

Every call has a fixed price in credits. Buy credits in packs, starting at $10 for 20,000 credits, by card
through Stripe Checkout. Your first workspace gets 200 credits when you verify your email. Credits never expire:
they stay in your workspace until you use them, and nothing renews.

| Call | Price | Per 1,000 calls | From our cache | Confirmed not found |
|---|---|---|---|---|
| Company, by LinkedIn URL (`POST /v1/company`) | 2 credits | $1.00 to $0.50 | 1 credit | 1 credit, free from our cache |
| Company, by website domain (`POST /v1/domain`) | 4 credits | $2.00 to $1.00 | 2 credits | 4 credits, free from our cache |
| Web search (`POST /v1/search`) | 1 credit | $0.50 to $0.25 | 1 credit | n/a |
| Cache check (`POST /v1/cache`) | Free | Free | n/a | n/a |

Prices are in USD, VAT excluded. The current prices are always at `GET https://api.happyfetch.net/v1/pricing`.

## What is charged

| Outcome | What happens | Error codes |
|---|---|---|
| A result: company data, or a completed search (even with zero results) | Charged the call's price; a lookup from our cache costs less | none |
| A definitive "no such company" | Charged 1 credit by LinkedIn company URL, 4 by website domain when we look it up; free when the answer comes from our cache | [`not_found`](/docs/errors#not_found), [`unresolvable_id`](/docs/errors#unresolvable_id) |
| We couldn't complete the call | Charged, then refunded automatically in the same request | [`upstream_error`](/docs/errors#upstream_error), [`parse_error`](/docs/errors#parse_error), [`blocked`](/docs/errors#blocked), [`source_rate_limited`](/docs/errors#source_rate_limited), [`timeout`](/docs/errors#timeout), [`internal_error`](/docs/errors#internal_error) |
| The request was rejected before any work | Never charged | [`invalid_request`](/docs/errors#invalid_request), [`invalid_person_reference`](/docs/errors#invalid_person_reference), [`invalid_domain`](/docs/errors#invalid_domain), [`invalid_company_reference`](/docs/errors#invalid_company_reference), [`unauthorized`](/docs/errors#unauthorized), [`insufficient_credits`](/docs/errors#insufficient_credits), [`route_not_found`](/docs/errors#route_not_found), [`idempotency_key_in_use`](/docs/errors#idempotency_key_in_use), [`idempotency_key_reused`](/docs/errors#idempotency_key_reused), [`rate_limited`](/docs/errors#rate_limited), [`concurrency_limited`](/docs/errors#concurrency_limited), [`no_capacity`](/docs/errors#no_capacity) |

The refund happens inside the same request: the error response already shows `credits_charged: 0`.

## Seeing what you spent

- Every call that reaches billing carries `X-Credits-Charged` and `X-Credits-Remaining`, with the same
  numbers in `meta`. A request rejected before any work has `meta.credits_charged: 0` and no credit headers.
- The console's **ledger** lists every credit movement (purchases, calls, refunds, grants) with the
  running balance. Each call line links to the request that caused it.
- We email the workspace's owners when the balance runs low. Change the level in the console.

## Invoices

Every purchase comes with an invoice. Add your company name, address and VAT number at checkout and they
appear on it. The console's billing page links to each invoice, with a PDF, next to its purchase.

## Refunds of purchases

If a card payment is refunded or disputed, the credits it bought are removed. Credits already spent
stay spent, and we'll contact you about any shortfall.