Wellward
See my plan matches

← Guides

Billing and what counts as a Read

Try it on a test key

curl -s "https://api.wellwardhealth.com/v1/usage" -H "Authorization: Bearer $WELLWARD_KEY"

Test keys are free. Live use is billed monthly in arrears, per usage: per Read and per completed price request. There is no minimum, no free allowance and no volume band.

The rates

The rates are on the pricing page — the one place they are stated, so this page and the reference cannot drift from it. What you pay for:

  • Reads — each call to GET /v1/prices, GET /v1/prices/{id}, GET /v1/benchmarks or an MCP price tool that returns data. Each page of results is a separate Read.
  • Completed price requests — a request that obtains a price. It is not billed if we obtain no quote, or if the only quote is outside the reasonable band of prices for that service in that market or comparable markets. A request obtains a price when a new price for that service, near the location you asked about and quoted on or after the day you asked, is published while it is open; every request is billed on its own. The price then becomes available to every customer, and later Reads of it are billed as Reads.
  • Everything else is free, including /v1/coverage and /v1/search, and nothing a test key does is ever billed.

What counts as a Read

This is the definition we bill by:

  • A Read is one successful (HTTP 2xx) call to a price or benchmark endpoint that returns data — one or more Price Records, or a benchmark distribution — regardless of how many Price Records are returned in that response.
  • A single call returning prices for one service near one location (typically several provider locations) is one Read. Each page of results is a separate Read. A page holds up to 20 results, and every /v1/prices response carries summary.count — the total number of results — so you know how many pages (and Reads) a full pull takes before you fetch them.
  • Calls returning HTTP 4xx or 5xx, empty results, or only provider directory records without prices are not Reads. Calls to authentication, status, metadata, usage, webhook and Request-status endpoints are not Reads.
  • A call that fails with a server error (5xx) is not a Read. Identical calls within 60 seconds from the same account are counted once.
  • Our usage logs are the record of Reads. You can see running usage and download monthly statements in the developer dashboard.

The billed endpoints are GET /v1/prices, GET /v1/prices/{id}, GET /v1/benchmarks, and the MCP tools find_cash_prices, explain_price and get_cash_benchmark. Everything else — /v1/coverage, /v1/search, /v1/services, /v1/usage, /v1/prices/changes, webhooks, request status — is free.

Watching your usage

GET /v1/usage returns Reads, other calls, test calls and requests by day or month, with the current rate and month-to-date charge. The dashboard's Usage tab and your monthly statement show the same numbers, computed from the same records.

Paying

  • Card: added in the dashboard through Stripe. You are charged on the 1st for the month just closed.
  • Invoice: for larger accounts, by arrangement — net 30. Email hello@wellwardhealth.com.

Statements (PDF) are in the dashboard's Billing tab.

Spending cap

Set a monthly cap in the dashboard. We email your admins and billing members — and send usage.threshold_reached — at 50%, 80% and 100%. At the cap, everything that costs money stops until you raise it or the month ends: Reads (including the MCP price tools) and new live price requests return 402 spend_cap_reached — or, through MCP, a tool error. Free endpoints keep working.

New accounts have a lower monthly cap (shown in the dashboard and on the pricing page) until the first invoice is paid, whatever cap you set (you can set a lower one). After that, your own cap applies. Email hello@wellwardhealth.com to lift it sooner.

If a payment fails

Stripe retries automatically. If it cannot collect, we email you and send billing.payment_failed. If the invoice is still unpaid ten days later, live keys are suspended (402 payment_required); test keys keep working. Paying the outstanding invoice reactivates them straight away: open Billing → Manage billing & invoices. Adding or replacing a card makes it the card we charge from then on, but does not by itself pay an invoice Stripe has stopped retrying.

API reference · Dashboard · Questions: hello@wellwardhealth.com