Vai al contenuto
Address Validation iO

Questa documentazione è disponibile solo in inglese.

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"

A month's usage looks like this:

JSON
{
  "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"

Full reference

The full usage schema is in the API reference.