Skip to content
Address Validation iO

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
  }'

The answer is the stored order result:

JSON
{
  "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 PUT after a timeout or a 5xx.
  • 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: true checks 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"

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" } }'

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.