API
Usage
Read your shop's metered usage and current prices with GET /v1/usage and the last twelve months with GET /v1/usage/months.
Two endpoints show what your shop has used: GET /v1/usage for one month, with your current prices, and GET /v1/usage/months for up to the last 12 months. Months are calendar months in UTC. Amounts are in micro-USD (1,000,000 = $1.00) and are always the prices AVIO charges you.
One month
GET /v1/usage takes an optional period query parameter in yyyy-mm form. Without it you get the current month. Any other format answers 400 invalid_period.
curl "https://api.address-validation.io/v1/usage?period=2026-10" \
-H "Authorization: Bearer $AVIO_API_KEY"const response = await fetch("https://api.address-validation.io/v1/usage?period=2026-10", {
headers: { Authorization: `Bearer ${process.env.AVIO_API_KEY}` },
});
if (!response.ok) {
throw new Error(`AVIO ${response.status}: ${(await response.json()).error}`);
}
const usage = await response.json();
console.log(`${usage.orders} orders, $${(usage.accruedMicros / 1e6).toFixed(2)}`);<?php
$ch = curl_init('https://api.address-validation.io/v1/usage?period=2026-10');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AVIO_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$usage = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("AVIO {$status}: {$usage['error']}");
}
printf("%d orders, $%.2f\n", $usage['orders'], $usage['accruedMicros'] / 1e6);import os
import requests
response = requests.get(
"https://api.address-validation.io/v1/usage",
params={"period": "2026-10"},
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
timeout=5,
)
response.raise_for_status()
usage = response.json()
print(f"{usage['orders']} orders, ${usage['accruedMicros'] / 1e6:.2f}")A month's usage looks like this:
{
"period": "2026-10",
"currency": "USD",
"addressChecks": 1840,
"providerChecks": 1210,
"orders": 412,
"freeOrders": 0,
"repeatOrders": 37,
"accruedMicros": 20107500,
"emailChecks": 120,
"phoneChecks": 0,
"repeatSavedMicros": 832500,
"accruedCounted": true,
"byProvider": { "loqate": 1530, "google": 310 },
"emailByProvider": { "bouncer": 120 },
"phoneByProvider": {},
"meteredEmailChecks": 120,
"meteredPhoneChecks": 0,
"emailAccruedMicros": 2400000,
"phoneAccruedMicros": 0,
"prices": {
"verifiedOrderMicros": 45000,
"verifiedOrderFrom": false,
"includedPerMonth": 0,
"repeatDiscountPercent": 50,
"emailCheckMicros": 20000,
"phoneCheckMicros": 20000
},
"metering": "accrual",
"countersSince": "2026-10-12"
}The values above are an example. Your own prices are in prices; the published plans are on the pricing page.
Counts
| Field | Meaning |
|---|---|
addressChecks |
Address checks in the month. |
providerChecks |
The address checks a provider answered (not served from cache). |
byProvider |
addressChecks per provider that answered. |
orders |
Metered verified orders. |
freeOrders |
The part of orders covered by your one-time free checks: verified, never charged. |
repeatOrders |
Orders that reused an answer another of your orders already paid for, charged at the repeat discount. |
emailChecks, phoneChecks |
Email and phone checks in the month. |
emailByProvider, phoneByProvider |
Email and phone checks per provider that answered. |
meteredEmailChecks, meteredPhoneChecks |
The billable email and phone checks. |
Amounts
| Field | Meaning |
|---|---|
currency |
Always USD. |
accruedMicros |
The month's metered amount: orders plus email and phone checks. |
emailAccruedMicros, phoneAccruedMicros |
The email and phone parts of accruedMicros. |
repeatSavedMicros |
What the repeat discount saved you this month. |
accruedCounted |
false while the month has no running total yet; accruedMicros is then 0. |
metering |
accrual: the charged prices accrue and are not invoiced yet. shopify-billing: billed through Shopify. |
countersSince |
The UTC day from which your shop's charges are counted. |
Prices
prices shows your shop's current terms, whatever period you asked for:
| Field | Meaning |
|---|---|
verifiedOrderMicros |
Price per verified order beyond includedPerMonth. |
verifiedOrderFrom |
true when the order price depends on the provider; verifiedOrderMicros is then the lowest one. |
includedPerMonth |
Verified orders per month at no charge. |
repeatDiscountPercent |
Discount on an order whose answer another of your orders already paid for. |
emailCheckMicros, phoneCheckMicros |
Price per email and phone check with your configured providers. |
Standalone address checks (POST /v1/addresses/validate) are not metered; they show up in addressChecks but add nothing to accruedMicros.
The last months
GET /v1/usage/months returns { months, metering, countersSince }. months starts with the current month and goes back, newest first. Each entry has the same fields as GET /v1/usage, without prices. A month without usage is all zeros.
The optional count parameter picks how many months, from 1 to 12 (default 12). A bad count answers 400 invalid_query with "fields": ["count"]. This endpoint shares an hourly limit of 1,000 requests with the log and stats reads, then answers 429 rate_limited.
curl "https://api.address-validation.io/v1/usage/months?count=3" \
-H "Authorization: Bearer $AVIO_API_KEY"const response = await fetch("https://api.address-validation.io/v1/usage/months?count=3", {
headers: { Authorization: `Bearer ${process.env.AVIO_API_KEY}` },
});
const { months } = await response.json();
for (const month of months) console.log(month.period, month.orders);<?php
$ch = curl_init('https://api.address-validation.io/v1/usage/months?count=3');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AVIO_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($result['months'] as $month) {
echo $month['period'], ' ', $month['orders'], PHP_EOL;
}import os
import requests
response = requests.get(
"https://api.address-validation.io/v1/usage/months",
params={"count": 3},
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
timeout=5,
)
for month in response.json()["months"]:
print(month["period"], month["orders"])Full reference
The full usage schema is in the API reference.