Wellward

← 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 per usage — per Read and per completed price request — and charged daily: shortly after midnight US Eastern, we charge your card for the previous day (US Eastern) in one invoice. Days without billable usage aren't charged. 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, all-in or a component price (part of the service, such as a surgeon's fee alone). It is not billed if we obtain no quote, if the only quote is an add-on on its own (such as skin testing priced per antigen with no consult price) or a required consult on its own (such as the consult before a colonoscopy, with no colonoscopy price), 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, while it is open, it produces a price for that service — at a provider you listed (including a price we already held for them, within your max_age_days if you sent it; a listed provider whose price is older than that is called again), or near the location you asked about and quoted on or after the day you asked. Every request is billed on its own, and once, however many prices it carries. 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.
  • A response doesn't say whether it was a Read; our usage logs are the record of Reads, and /v1/usage shows them. You can see running usage, and each day's charge and invoice, 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 invoices show the same numbers, computed from the same records. (/v1/usage groups days by UTC; invoices are by US Eastern day, so a day's totals can differ between the two at the edges, never in sum.)

Paying

  • Card: added in the dashboard through Stripe. You are charged daily, shortly after midnight US Eastern, for the previous day's Reads and completed price requests — one invoice per day with usage. A price request counts on the day it completes.
  • Invoice: for larger accounts, by arrangement — net 30. Email hello@wellwardhealth.com.

Daily charges (with a link to each invoice) and statements for months before October 2026 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