Developers / Billing

Billing

Prepaid or postpaid, what counts as billable, and how to reconcile a statement against your own logs.

Prepaid or postpaid

Accounts are one or the other, agreed when you are onboarded. GET /v1/account tells you which.

Prepaid. You top up a balance and calls draw it down. balanceEur is returned on your account, and X-Credit-Balance comes back on every purchase so you can watch it without a second request. When it reaches zero, report requests return 402 INSUFFICIENT_CREDIT until you top up. Reading reports you have already bought keeps working.

If you give us a warning level we email you once when the balance drops below it. Once per depletion, not on every call, so the warning stays worth reading.

Postpaid. Calls accrue through the month and we invoice at the end of your billing period. If your account has a credit limit, reaching it returns 402 the same way.

What counts as billable

One charge per lookup that produced a report. Specifically:

  • A completed POST /v1/reports is billable.
  • A repeat lookup of the same vehicle within your charge window is free, unless your account is set up to bill every call.
  • GET /v1/reports/{reportId} is always free, for the life of the access window.
  • Anything that is not a 200 is never billed. Errors, rate limits and outages cost you nothing.
  • Account endpoints are free: /v1/account, /v1/account/usage, /v1/account/statements and /v1/ping.

A report that is thin because little is recorded for that vehicle is still a completed lookup, and is billed. We searched, and the answer was that there is not much. If a whole class of vehicle is consistently returning less than you expected, tell us. That is worth investigating.

Checking your usage

curl "https://api.mrvin.com/v1/account/usage?from=2026-08-01&to=2026-09-01" \
  -H "Authorization: Bearer mrvin_live_your_key_here"

You get a breakdown per day with two counts.

  • totalCalls, every call you made, including failures and free repeats.
  • billableCalls, the ones that were charged.

Both are there deliberately. If we only showed the smaller number you would have no way to check our arithmetic against your own logs, and the gap would look like calls going missing. The gap is your errors plus your free repeats.

Statements

At the end of each billing period we generate a statement and email it to your contact address. It breaks usage down by endpoint, shows total and billable calls, and gives the amount. For prepaid accounts it also shows the closing balance. For postpaid, an invoice follows separately.

Past statements are available any time.

curl https://api.mrvin.com/v1/account/statements \
  -H "Authorization: Bearer mrvin_live_your_key_here"

Amounts are summed from the price recorded on each individual call at the moment it was made. If a price changes mid period, calls before the change are billed at the old price and calls after at the new one, so a statement always reflects what you were actually quoted and you can reconcile it line by line against your own records.

Questions about a bill

Reply to the statement email, or write to us with the period in question. Every charge is traceable to the individual API call that produced it, so a query gets an answer rather than an assurance.