API
Orders
Submit an order for checking with the idempotent PUT /v1/orders/{orderId}, read it back, record a correction and erase it.
The order endpoints check the shipping address (and optionally the billing address, email and phone) of a placed order and store the result under your own order id. You submit an order once it is placed, read the result back later, record the customer's correction, and erase the order when you have to delete customer data.
Order ids
{orderId} is your platform's order id: 1 to 64 characters from A-Z, a-z, 0-9, ., _, : and -. URL-encode it in the path. Any other id answers 400 invalid_order_id.
Submit an order
PUT /v1/orders/{orderId} checks the order and stores the result.
| Field | Type | Description |
|---|---|---|
shippingAddress |
address | Required. Same shape as in Validate an address. |
orderNumber |
string | The order number your customers see, such as #1001. Optional. |
billingAddress |
address | Checked too when you send it. Optional. |
email, checkEmail |
string, boolean | The buyer's email, checked when checkEmail is true. |
phone, checkPhone |
string, boolean | The buyer's phone, checked when checkPhone is true. The shipping country is used for numbers without a prefix. |
force |
boolean | Check again even if the shipping address hasn't changed. |
curl -X PUT https://api.address-validation.io/v1/orders/1001 \
-H "Authorization: Bearer $AVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"orderNumber": "#1001",
"shippingAddress": {
"firstName": "Jane", "lastName": "Doe",
"address1": "Unter den Linden 77", "city": "Berlin", "zip": "10117", "countryCode": "DE"
},
"email": "jane.doe@example.com",
"checkEmail": true
}'const orderId = "1001";
const response = await fetch(`https://api.address-validation.io/v1/orders/${encodeURIComponent(orderId)}`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.AVIO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
orderNumber: "#1001",
shippingAddress: {
firstName: "Jane", lastName: "Doe",
address1: "Unter den Linden 77", city: "Berlin", zip: "10117", countryCode: "DE",
},
email: "jane.doe@example.com",
checkEmail: true,
}),
signal: AbortSignal.timeout(5000),
});
if (!response.ok) {
throw new Error(`AVIO ${response.status}: ${(await response.json()).error}`);
}
const order = await response.json();<?php
$orderId = '1001';
$ch = curl_init('https://api.address-validation.io/v1/orders/' . rawurlencode($orderId));
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_POSTFIELDS => json_encode([
'orderNumber' => '#1001',
'shippingAddress' => [
'firstName' => 'Jane', 'lastName' => 'Doe',
'address1' => 'Unter den Linden 77', 'city' => 'Berlin', 'zip' => '10117', 'countryCode' => 'DE',
],
'email' => 'jane.doe@example.com',
'checkEmail' => true,
]),
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AVIO_API_KEY'), 'Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$order = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("AVIO {$status}: {$order['error']}");
}import os
from urllib.parse import quote
import requests
order_id = "1001"
response = requests.put(
f"https://api.address-validation.io/v1/orders/{quote(order_id, safe='')}",
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
json={
"orderNumber": "#1001",
"shippingAddress": {
"firstName": "Jane", "lastName": "Doe",
"address1": "Unter den Linden 77", "city": "Berlin", "zip": "10117", "countryCode": "DE",
},
"email": "jane.doe@example.com",
"checkEmail": True,
},
timeout=5,
)
response.raise_for_status()
order = response.json()The answer is the stored order result:
{
"orderId": "1001",
"orderNumber": "#1001",
"decision": "valid",
"status": "validated",
"address": {
"firstName": "Jane", "lastName": "Doe",
"address1": "Unter den Linden 77", "city": "Berlin", "zip": "10117", "countryCode": "DE"
},
"addressHash": "9b2e4f61c0a87d35e1f9c2b4a6d8e0f13579bdf2468ace013579bdf2468ace01",
"verdict": {
"status": "deliverable",
"provider": "loqate",
"granularity": "premise",
"changes": [], "missing": [], "unverified": [], "suggestions": []
},
"issues": [],
"email": { "result": "valid" },
"validatedAt": "2026-11-16T09:41:27.512Z",
"metered": true
}| Field | Meaning |
|---|---|
decision, verdict, issues, addressHash |
The shipping address check, as described in Validate an address. |
status |
validated (checked), fixed (a correction changed the address) or confirmed (the customer kept the address). |
address |
The shipping address as stored. After a correction, the corrected one. |
billing |
{ decision, verdict } of the billing address, when you sent one. |
email, phone |
The email and phone results, as in Validate an email and a phone. Left out when not checked, or when the hourly limit was used up. |
validatedAt, correctedAt |
When the order was last checked and corrected (ISO 8601). |
correctableUntil |
Until when the customer can still correct the address, if your shop sets a time limit. |
metered |
Whether the order has been metered. |
addressRules, rewrite |
Your address rules that matched and the rewritten address, as in a standalone check. |
Idempotency
PUT is idempotent by order id and shipping address:
- The same order with the same shipping address returns the stored result. Nothing is checked again and nothing is metered again, so you can safely retry a
PUTafter a timeout or a5xx. - A different shipping address checks the order again. Re-checks of known orders have their own hourly limit; when it is used up the re-check answers
decision: "skipped". force: truechecks again even with the same address.
An order is metered once, the first time its shipping address gets an answer from a provider. Re-checks and corrections don't meter it again. For prices, see Pricing.
409 order_conflict means another request saved a different address for the same order while yours ran, or the order was erased. Send the order again as it is now in your system.
Read an order
GET /v1/orders/{orderId} returns the stored order result in the same shape, or 404 order_not_found. DELETE uses the same path (see Erase an order).
curl https://api.address-validation.io/v1/orders/1001 \
-H "Authorization: Bearer $AVIO_API_KEY"const response = await fetch("https://api.address-validation.io/v1/orders/1001", {
headers: { Authorization: `Bearer ${process.env.AVIO_API_KEY}` },
});
const order = response.status === 404 ? undefined : await response.json();<?php
$ch = curl_init('https://api.address-validation.io/v1/orders/1001');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AVIO_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$body = curl_exec($ch);
$order = curl_getinfo($ch, CURLINFO_RESPONSE_CODE) === 404 ? null : json_decode($body, true);
curl_close($ch);import os
import requests
response = requests.get(
"https://api.address-validation.io/v1/orders/1001",
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
timeout=5,
)
order = None if response.status_code == 404 else response.json()Submit a correction
When the customer confirms or edits the address (for example from a correction email or page), send it with POST /v1/orders/{orderId}/correction:
| Field | Description |
|---|---|
address |
The address the customer chose. Required. |
by |
customer (default) or admin, when your shop's staff applied a suggestion in your admin. |
If the address is unchanged, the order becomes confirmed. Otherwise AVIO checks the new address and the order becomes fixed. AVIO can't edit the order in your store: write a fixed address back to your order yourself. Corrections are never metered.
curl https://api.address-validation.io/v1/orders/1001/correction \
-H "Authorization: Bearer $AVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "address": { "address1": "Unter den Linden 77", "city": "Berlin", "zip": "10117", "countryCode": "DE" } }'const address = { address1: "Unter den Linden 77", city: "Berlin", zip: "10117", countryCode: "DE" };
const response = await fetch("https://api.address-validation.io/v1/orders/1001/correction", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVIO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ address }),
});
const corrected = await response.json();<?php
$address = ['address1' => 'Unter den Linden 77', 'city' => 'Berlin', 'zip' => '10117', 'countryCode' => 'DE'];
$ch = curl_init('https://api.address-validation.io/v1/orders/1001/correction');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['address' => $address]),
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AVIO_API_KEY'), 'Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$corrected = json_decode(curl_exec($ch), true);
curl_close($ch);import os
import requests
address = {"address1": "Unter den Linden 77", "city": "Berlin", "zip": "10117", "countryCode": "DE"}
response = requests.post(
"https://api.address-validation.io/v1/orders/1001/correction",
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
json={"address": address},
timeout=5,
)
corrected = response.json()The answer is the updated order result. Errors to handle: 404 order_not_found, 409 correction_locked (a customer correction after correctableUntil; by: "admin" is exempt), 409 order_conflict (the order changed meanwhile; reload it and try again) and 429 rate_limited (the hourly correction limit).
Erase an order
DELETE /v1/orders/{orderId} erases the order and its log entries, for example when a customer asks you to delete their data. It answers { "deleted": true }. A metered order keeps only its id and when it was metered, so sending it again is never metered twice. Send it like the GET above with -X DELETE (cURL), method: "DELETE" (fetch), CURLOPT_CUSTOMREQUEST => 'DELETE' (PHP) or requests.delete (Python).
Full reference
The full order schema is in the API reference.