{"openapi":"3.1.0","info":{"title":"Address Validation iO platform API","version":"1","description":"Address, email and phone validation and shop configuration for every platform. Server-to-server only: keys never reach a browser. Parts only some platforms carry, Shopify-only ones included, are marked with `x-avio-platforms` (the platforms that carry them). v1 is additive-only. Errors are `{ \"error\": \"<code>\" }`; every response carries `x-avio-request-id`. Show Google's attribution (\"Google Maps\", the logo where you can) when `verdict.suggestionsProvider` (else `verdict.provider`) is `google`."},"servers":[{"url":"https://api.address-validation.io"}],"security":[{"apiKey":[]}],"paths":{"/v1/health":{"get":{"operationId":"health","summary":"Liveness check","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/faqs":{"get":{"operationId":"faqs","summary":"The FAQ staff publish for one surface (`tag`), in a locale (English fallback). No key; any origin may read it (`Access-Control-Allow-Origin: *`), cacheable for 5 minutes. Never metered","security":[],"parameters":[{"name":"tag","in":"query","required":true,"description":"Where the questions show","schema":{"type":"string","enum":["shopify","shopware","woocommerce","website"]}},{"name":"locale","in":"query","required":false,"description":"`en`, `de`, `fr`, `es` (`de-DE` works too) are translated, anything else is English; a missing translation is English. Default: `en`","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Faqs"}}}},"400":{"description":"`invalid_query` (with `fields`): `tag` missing or unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/changelog":{"get":{"operationId":"changelog","summary":"What changed for merchants, newest first: the product changelog entries staff approved and published, optionally only the lines for one platform. No key; any origin may read it (`Access-Control-Allow-Origin: *`), cacheable for 5 minutes. Never metered","security":[],"parameters":[{"name":"limit","in":"query","required":false,"description":"Most entries to read, 1 to 50 (default 20). With `platform`, entries without a line for it are left out, so a page can hold fewer","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"name":"before","in":"query","required":false,"description":"The previous page's `nextCursor`; absent for the newest entries","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"platform","in":"query","required":false,"description":"Only lines for this platform (`api` = API shops)","schema":{"type":"string","enum":["shopify","woocommerce","shopware","api"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Changelog"}}}},"400":{"description":"`invalid_query` (with `fields`): `limit`, `before` or `platform` invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/status":{"get":{"operationId":"status","summary":"Health of Address Validation iO's services and validation providers, for status pages. No key; any origin may read it (`Access-Control-Allow-Origin: *`), cacheable for 1 minute. Never metered","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/v1/me":{"get":{"operationId":"me","summary":"The shop and key of this request","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantInfo"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/addresses/validate":{"post":{"operationId":"validateAddress","summary":"Validate an address (free, quota-limited; fails open with `decision: skipped`)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateAddressBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressCheck"}}}},"400":{"description":"`invalid_body`; `provider_override_not_allowed`: `provider` sent, but the shop may not choose its provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: the `api-test` quota of `context: test` is spent; staff's hourly limit replaces its limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/validate":{"post":{"operationId":"validateEmail","summary":"Validate an email address","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateEmailBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailCheckResult"}}}},"400":{"description":"`invalid_body`; `provider_override_not_allowed`: `provider` sent, but the shop may not choose its provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/phones/validate":{"post":{"operationId":"validatePhone","summary":"Validate a phone number","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatePhoneBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneCheckResult"}}}},"400":{"description":"`invalid_body`; `provider_override_not_allowed`: `provider` sent, but the shop may not choose its provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{orderId}":{"put":{"operationId":"submitOrder","summary":"Validate and store an order (idempotent by id and shipping address; metered once)","parameters":[{"name":"orderId","in":"path","required":true,"description":"The platform's order id (URL-encoded).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResult"}}}},"400":{"description":"`invalid_body` or `invalid_order_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`order_conflict`: another address was saved during the request, or the order erased; send the order as it is now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getOrder","summary":"The stored order result","parameters":[{"name":"orderId","in":"path","required":true,"description":"The platform's order id (URL-encoded).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResult"}}}},"400":{"description":"`invalid_order_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`order_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteOrder","summary":"Erase the order and its logs (GDPR)","parameters":[{"name":"orderId","in":"path","required":true,"description":"The platform's order id (URL-encoded).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"`invalid_order_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{orderId}/correction":{"post":{"operationId":"correctOrder","summary":"The customer's correction (`by: admin`: staff applied a suggestion): `confirmed` when unchanged, else `fixed`","parameters":[{"name":"orderId","in":"path","required":true,"description":"The platform's order id (URL-encoded).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorrectionBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResult"}}}},"400":{"description":"`invalid_body` or `invalid_order_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`order_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`order_conflict`: another save won (not this correction's double submit); send it again as the order is now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"operationId":"usage","summary":"Metered usage of one month (UTC) and the shop's current prices","parameters":[{"name":"period","in":"query","required":false,"description":"`yyyy-mm`, default: the current month","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageWithPrices"}}}},"400":{"description":"`invalid_period`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/capabilities":{"get":{"operationId":"capabilities","summary":"What the shop can use: checks, providers with charged prices, settings areas and every feature with how it runs on the shop's platform","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connection":{"put":{"operationId":"connect","summary":"Report the integration (on key save, version change and daily); answers the capabilities. Writes only what changed","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionReport"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"400":{"description":"`invalid_body` (with `fields`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/uninstall":{"post":{"operationId":"uninstall","summary":"The integration was deleted: marks the shop uninstalled and, unless `keepData`, erases its orders, their logs and the check details in the analytics archive (bounded; the rest expires; the pseudonymous general part of the archive stays until its 400 days are up). Keys stay valid; the next connection report reinstalls. Idempotent","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UninstallBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UninstallResult"}}}},"400":{"description":"`invalid_body` (with `fields`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/settings":{"get":{"operationId":"settings","summary":"The shop's settings, their version and the choices (charged prices only)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformSettings"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/settings/{area}":{"put":{"operationId":"saveSettings","summary":"Save one settings area (`orders`, `delivery-points`, `checkout`, `contact`, `analytics`; `store` for WooCommerce and Shopware shops, in the platform's shape; `holds`, `emails`, `accounts` for Shopify shops); answers the whole settings with the new versions","parameters":[{"name":"area","in":"path","required":true,"description":"`x-avio-platforms` names, per area, the platforms whose shops save it here.","schema":{"type":"string","enum":["orders","delivery-points","checkout","address-rules","contact","analytics","store","holds","emails","accounts"],"x-avio-platforms":{"orders":["shopify","woocommerce","shopware","custom"],"delivery-points":["shopify","woocommerce","shopware","custom"],"checkout":["shopify","woocommerce","shopware","custom"],"address-rules":["shopify","woocommerce","shopware","custom"],"contact":["shopify","woocommerce","shopware","custom"],"analytics":["shopify","woocommerce","shopware","custom"],"store":["woocommerce","shopware"],"holds":["shopify"],"emails":["shopify"],"accounts":["shopify"]}}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformSettings"}}}},"400":{"description":"`invalid_body` (with `fields`) or `invalid_area` (an area the shop's platform doesn't save here: see `x-avio-platforms`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`settings_conflict`: `version` is stale (a save that changes nothing answers 200 instead)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/routes":{"get":{"operationId":"routes","summary":"The shop's effective routes (its own rows over Address Validation iO's recommended ones, each with its `source`), the recommended routes and the choices","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformRoutes"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/routes/{country}":{"put":{"operationId":"saveRoute","summary":"Save a country's own route while the row shown is still `expected` (null: none); a recommended row becomes `custom`","parameters":[{"name":"country","in":"path","required":true,"description":"A country of `choices.countries`, or `default` for the `*` row.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformRoutes"}}}},"400":{"description":"`invalid_body` (with `fields`) or `invalid_country`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`route_conflict`: the stored row is not `expected` (a row that already has the values answers 200)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteRoute","summary":"Delete a country's own route while it is still `expected`, so it follows the recommended route again (no own row answers 200)","parameters":[{"name":"country","in":"path","required":true,"description":"A country of `choices.countries`, or `default` for the `*` row.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteRouteBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformRoutes"}}}},"400":{"description":"`invalid_body` or `invalid_country`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`route_conflict`: the stored row is not `expected` (a row that already has the values answers 200)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`body_too_large` (over 16 KB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/logs":{"get":{"operationId":"logs","summary":"The shop's app log, newest first (90 days, paged), with each provider call's response time; never provider cost","parameters":[{"name":"from","in":"query","required":false,"description":"`yyyy-mm-dd`, inclusive, within the last 90 days. Default: 6 days before `to`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"`yyyy-mm-dd`, inclusive. Default: today in `timeZone`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"timeZone","in":"query","required":false,"description":"The days' time zone: an IANA name or `±hh:mm`. Default: UTC.","schema":{"type":"string","maxLength":64}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["validation","address","correction","email","phone","hold","tag","flow","billing","settings","app","error"]}},{"name":"result","in":"query","required":false,"schema":{"type":"string","enum":["valid","warn","invalid","skipped"]}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["checkout","order-created","order-updated","admin","bulk","flow","customer","widget-address","test","ab-test"]}},{"name":"order","in":"query","required":false,"description":"An order number, with or without `#` (matched against `orderName`).","schema":{"type":"string","maxLength":64}},{"name":"problems","in":"query","required":false,"description":"`1`: warnings and errors only.","schema":{"type":"string","const":"1"}},{"name":"pageSize","in":"query","required":false,"description":"Default: 50.","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `page.cursor` of the page shown.","schema":{"type":"string","maxLength":1024}},{"name":"direction","in":"query","required":false,"description":"With `cursor`: `next` (older, the default) or `previous` (newer).","schema":{"type":"string","enum":["next","previous"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogPage"}}}},"400":{"description":"`invalid_query` (with `fields`), `invalid_range` (a bad day, `from` after `to`, a day over 90 days ago or after tomorrow) or `invalid_cursor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` (1000 log reads per hour and shop)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats":{"get":{"operationId":"stats","summary":"The Analytics numbers over 7, 30, 90 days or 12 months in UTC buckets; charged prices only, never provider cost","parameters":[{"name":"days","in":"query","required":false,"description":"7, 30 or 90: that many UTC days ending today, in daily buckets. 365: this month and the 11 before, in monthly buckets. Default: 30.","schema":{"type":"string","enum":["7","30","90","365"]}},{"name":"daily","in":"query","required":false,"description":"`1`: add `daily`, the checks and their sources per stored day.","schema":{"type":"string","const":"1"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformStats"}}}},"400":{"description":"`invalid_query` (with `fields`: `days`, `daily`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` (shared with `GET /v1/logs`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats/sources":{"get":{"operationId":"statsSources","summary":"Address checks per source (checkout, admin, order, correction) per day, week or month over UTC days, as the Logs chart shows them","parameters":[{"name":"from","in":"query","required":false,"description":"`yyyy-mm-dd` (UTC), inclusive. Default: 6 days before `to`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"`yyyy-mm-dd` (UTC), inclusive: at most tomorrow, and at most 366 days from `from` on. Default: today.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"bucket","in":"query","required":false,"description":"`week` buckets start on Monday. Default: `day`.","schema":{"type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsSources"}}}},"400":{"description":"`invalid_query` (with `fields`: `from`, `to`, `bucket`) or `invalid_range` (a day that doesn't exist, `from` after `to`, `to` after tomorrow or more than 366 days)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` (shared with `GET /v1/logs`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage/months":{"get":{"operationId":"usageMonths","summary":"The usage of the latest months, newest first; a month without usage is all zeros","parameters":[{"name":"count","in":"query","required":false,"description":"How many months, starting with the current one. Default: 12.","schema":{"type":"integer","minimum":1,"maximum":12}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageMonths"}}}},"400":{"description":"`invalid_query` (with `fields: [\"count\"]`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` (shared with `GET /v1/logs`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{orderId}/logs":{"get":{"operationId":"orderLogs","summary":"The order's history, oldest first (at most 300 rows; none for an unknown order)","parameters":[{"name":"orderId","in":"path","required":true,"description":"The platform's order id (URL-encoded).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderLogs"}}}},"400":{"description":"`invalid_order_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` (shared with `GET /v1/logs`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/banners":{"get":{"operationId":"banners","summary":"Address Validation iO's banners for the shop's admin: live, meant for the shop and not dismissed, by priority, in the merchant's locale (English fallback), as blocks and as escaped HTML. Never metered","parameters":[{"name":"locale","in":"query","required":false,"description":"The merchant's admin locale (`de`, `de-DE`); `en`, `de`, `fr`, `es` are translated, anything else is English. Default: the shop's locale","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Banners"}}}},"400":{"description":"`invalid_query` (with `fields: [\"locale\"]`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/banners/{id}/dismiss":{"post":{"operationId":"dismissBanner","summary":"Hide a dismissible banner for the shop (a repeat answers 200 too). Never metered","parameters":[{"name":"id","in":"path","required":true,"description":"The banner's id from `GET /v1/banners`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BannerDismissed"}}}},"401":{"description":"`missing_api_key` or `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`tenant_suspended`: the shop's API access is suspended; `not_available`: the shop's platform or the caller doesn't run this through the API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`banner_not_found`: unknown, not live or not dismissible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"`avk_<shop>_<keyId>_<secret>`"}},"schemas":{"AddressInput":{"type":"object","properties":{"firstName":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"company":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"address1":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"address2":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"zip":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"province":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"provinceCode":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"},"phone":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]}},"required":["countryCode"]},"ValidateAddressBody":{"type":"object","properties":{"address":{"$ref":"#/components/schemas/AddressInput"},"context":{"type":"string","enum":["checkout","account","other","test"]},"email":{"type":"string","maxLength":254},"provider":{"type":"string","enum":["loqate","google","postcode-eu","smarty"],"description":"Only for shops Address Validation iO staff allowed to choose (else 400 `provider_override_not_allowed`): asks this provider alone, no fallback."}},"required":["address"]},"ValidateEmailBody":{"type":"object","properties":{"email":{"type":"string","minLength":1,"maxLength":254},"provider":{"type":"string","enum":["bouncer","ses","loqate"],"description":"Only for shops Address Validation iO staff allowed to choose (else 400 `provider_override_not_allowed`): asks this provider alone, no fallback."}},"required":["email"]},"ValidatePhoneBody":{"type":"object","properties":{"phone":{"type":"string","minLength":1,"maxLength":64},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"},"provider":{"type":"string","enum":["offline","aws","loqate"],"description":"Only for shops Address Validation iO staff allowed to choose (else 400 `provider_override_not_allowed`): asks this provider alone, no fallback."}},"required":["phone"]},"OrderInput":{"type":"object","properties":{"orderNumber":{"type":"string","maxLength":64},"shippingAddress":{"$ref":"#/components/schemas/AddressInput"},"billingAddress":{"$ref":"#/components/schemas/AddressInput"},"email":{"type":"string","minLength":1,"maxLength":254},"checkEmail":{"type":"boolean"},"phone":{"type":"string","minLength":1,"maxLength":64},"checkPhone":{"type":"boolean"},"force":{"type":"boolean"}},"required":["shippingAddress"]},"CorrectionBody":{"type":"object","properties":{"address":{"$ref":"#/components/schemas/AddressInput"},"by":{"type":"string","enum":["customer","admin"]}},"required":["address"]},"SettingsBody":{"type":"object","properties":{"version":{"type":["string","null"]},"values":{"anyOf":[{"type":"object","properties":{"ignoreAddress2":{"type":"boolean"},"correctionLock":{"description":"When customers can no longer change an order's address. `stage`: the fulfillment stage from which on (Shopify and Shopware only; absent on a save: the platform's default, which a read always shows); a shipped order always locks. `afterHours`: 1 to 1440 hours after the order was placed; absent: no time limit. A read always answers it.","type":"object","properties":{"stage":{"type":"string","enum":["requested","in_progress","partially_fulfilled","fulfilled"]},"afterHours":{"type":"integer","minimum":1,"maximum":1440}}},"validateBilling":{"x-avio-platforms":["shopify"],"type":"boolean"},"channels":{"x-avio-platforms":["shopify"],"description":"Sales channels whose orders Address Validation iO checks: a source name such as `web`, or an app's numeric id. A Shopify shop's read can still answer a value saved in the old app's form (`gid://shopify/App/<id>`), which a save refuses, until a save sends `channels`.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z0-9_-]+$"}},"orderTags":{"x-avio-platforms":["shopify"],"type":"object","properties":{"enabled":{"type":"boolean"},"prefix":{"type":"string","maxLength":40},"format":{"type":"string","maxLength":40},"words":{"type":"object","properties":{"valid":{"type":"string","maxLength":40},"warn":{"type":"string","maxLength":40},"invalid":{"type":"string","maxLength":40},"unsupported":{"type":"string","maxLength":40},"skipped":{"type":"string","maxLength":40},"manual":{"type":"string","maxLength":40},"confirmed":{"type":"string","maxLength":40},"postBox":{"type":"string","maxLength":40},"emailValid":{"type":"string","maxLength":40},"emailInvalid":{"type":"string","maxLength":40},"emailUnknown":{"type":"string","maxLength":40},"phoneValid":{"type":"string","maxLength":40},"phoneInvalid":{"type":"string","maxLength":40},"phoneUnknown":{"type":"string","maxLength":40}},"required":["valid","warn","invalid","unsupported","skipped","manual","confirmed","postBox","emailValid","emailInvalid","emailUnknown","phoneValid","phoneInvalid","phoneUnknown"]}},"required":["enabled","prefix","format","words"]}},"required":["ignoreAddress2"]},{"type":"object","properties":{"default":{"type":"object","properties":{"poBox":{"type":"string","enum":["allow","block"]},"parcelLocker":{"type":"string","enum":["allow","block"]}},"required":["poBox","parcelLocker"]},"countries":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"poBox":{"type":"string","enum":["allow","block"]},"parcelLocker":{"type":"string","enum":["allow","block"]}},"required":["poBox","parcelLocker"]}}},"required":["default","countries"]},{"type":"object","properties":{"houseNumberCountries":{"type":"array","items":{"type":"string"}},"zipCountries":{"type":"array","items":{"type":"string"}},"maxAddressLength":{"type":"number"},"blockInvalidEmail":{"type":"boolean"},"blockDisposableEmail":{"type":"boolean"},"verifyEnabled":{"x-avio-platforms":["shopify"],"type":"boolean"},"blockOnInvalid":{"x-avio-platforms":["shopify"],"type":"boolean"},"autocompleteEnabled":{"x-avio-platforms":["shopify"],"description":"Address Validation iO's address suggestions in Shopify checkout (Plus only, also selected in the checkout editor). A read answers `false` until it is turned on.","type":"boolean"}},"required":["houseNumberCountries","zipCountries","maxAddressLength","blockInvalidEmail","blockDisposableEmail"]},{"type":"object","properties":{"rules":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,20}$"},"field":{"type":"string","enum":["address","address1","address2","city","zip","province"]},"match":{"type":"string","enum":["contains","word","equals","military","emoji","nonLatin","script","maxLength"]},"value":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[^\\p{Cc}\\p{Cs}]*$"},"scripts":{"minItems":1,"type":"array","items":{"type":"string","enum":["cyrillic","greek","han","kana","hangul","arabic","hebrew","thai","devanagari","armenian","georgian"]}},"max":{"type":"integer","minimum":1,"maximum":255},"action":{"type":"string","enum":["flag","block","replace","skip"]},"replacement":{"type":"string","maxLength":40,"pattern":"^[^\\p{Cc}\\p{Cs}]*$"},"countries":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}}},"required":["field","match","action"]}}},"required":["rules"],"description":"The merchant's address rules, every platform: at most 20, checked in order. `field`: one address field, or `address` for all of them. `match`: `contains`, `word` (whole words) and `equals` take `value` (at most 40 characters, case-insensitive); `military` (US APO/FPO/DPO and the Armed Forces states, field `address`), `emoji` and `nonLatin` take nothing; `script` takes `scripts`, a non-empty list without repeats of `cyrillic`, `greek`, `han` (Chinese characters, Japanese kanji), `kana`, `hangul`, `arabic`, `hebrew`, `thai`, `devanagari`, `armenian`, `georgian`, and matches a letter of any of them; `maxLength` takes `max` (1 to 255 characters). `action`: `flag` (a valid answer becomes `warn`), `block` (`invalid`, no provider call), `replace` (with `replacement`, before the check; not for `military`, `nonLatin`, `script` or `maxLength`), `skip` (`skipped`, no provider call; not for `maxLength`). `countries`: ISO alpha-2, at most 20; empty: every country. A rule without `id` gets the next free `r<n>`."},{"type":"object","properties":{"email":{"type":"object","properties":{"provider":{"type":"string"},"fallback":{"type":"string"}},"required":["provider"]},"phone":{"type":"object","properties":{"provider":{"type":"string"},"fallback":{"type":"string"}},"required":["provider"]}},"required":["email","phone"]},{"type":"object","properties":{"costPerFailedDeliveryMicros":{"type":"integer","minimum":0,"maximum":10000000000},"calculator":{"x-avio-platforms":["shopify"],"type":"object","properties":{"orders":{"type":"integer","minimum":0,"maximum":10000000},"badRate":{"type":"number","minimum":0,"maximum":100},"preventRate":{"type":"number","minimum":0,"maximum":100},"mode":{"type":"string","enum":["basic","advanced"]},"lines":{"type":"object","properties":{"returns":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":10000},"share":{"type":"number","minimum":0,"maximum":100}},"required":["value","share"]},"support":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":10000},"share":{"type":"number","minimum":0,"maximum":100}},"required":["value","share"]},"reshipping":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":10000},"share":{"type":"number","minimum":0,"maximum":100}},"required":["value","share"]},"restocking":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":10000},"share":{"type":"number","minimum":0,"maximum":100}},"required":["value","share"]}},"required":["returns","support","reshipping","restocking"]}},"required":["badRate","preventRate","mode","lines"]}},"required":["costPerFailedDeliveryMicros"]},{"type":"object","properties":{"fulfillmentHold":{"type":"object","properties":{"enabled":{"type":"boolean"},"releaseAfterHours":{"type":"integer","minimum":1,"maximum":720},"alertBeforeHours":{"type":"integer","minimum":0,"maximum":719},"alertIntervalHours":{"type":"integer","minimum":1,"maximum":168}},"required":["enabled","releaseAfterHours"]}},"required":["fulfillmentHold"],"description":"Shopify shops only: hold the fulfillment of an order whose address is invalid, released on correction or after `releaseAfterHours` (1 to 720). `alertBeforeHours` (0 to 719, absent = 12): email the shop that many hours before the release about held orders the customer hasn't fixed yet; 0 or at least `releaseAfterHours` = no email. `alertIntervalHours` (1 to 168, absent = 6): at most one such email per that many hours; an order may be listed up to that much earlier than `alertBeforeHours`. Needs the Fulfillment holds package; without it a save keeps the stored values."},{"type":"object","properties":{"customerEmails":{"type":"object","properties":{"enabled":{"type":"boolean"},"reminderHours":{"maxItems":5,"type":"array","items":{"type":"integer","minimum":1,"maximum":720}},"replyTo":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"merchantCopy":{"type":"boolean"},"linkTarget":{"type":"string","enum":["order-status","correction-page"]},"proxyPath":{"type":"string","maxLength":41}},"required":["enabled","reminderHours","merchantCopy"]}},"required":["customerEmails"],"description":"Shopify shops only: the correction request emails to the customer. `reminderHours`: at most 5 reminders, each 1 to 720 hours after the request. `replyTo`: where replies go; absent, the shop's email when the emails come from Address Validation iO's sender. `merchantCopy`: Bcc the shop's email on the request (not the reminders). `linkTarget`: where the email's link leads, `order-status` (the order status page, Address Validation iO's block) or `correction-page` (Address Validation iO's own page on the shop's app proxy); absent, by the shop's customer accounts: classic accounts get `correction-page`, anything else `order-status`. `proxyPath`: `/<a|apps|community|tools>/<subpath>`, only for a merchant who renamed Address Validation iO's app proxy in Shopify; absent, `/a/address-validation`."},{"type":"object","properties":{"customerAccount":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}},"required":["customerAccount"],"description":"Shopify shops only: the customer account extensions (the order list banner, the address check page, saved addresses)."},{"type":"object","properties":{"checkoutMode":{"type":"string","enum":["off","warn","block"]},"checkOrders":{"type":"boolean"},"checkBilling":{"type":"boolean"},"checkEmail":{"type":"boolean"},"checkPhone":{"type":"boolean"},"hold":{"type":"boolean"},"accountCheck":{"type":"boolean","x-avio-platforms":["woocommerce"]}},"required":["checkoutMode","checkOrders","checkBilling","checkEmail","checkPhone","hold","accountCheck"]},{"type":"object","properties":{"checkoutMode":{"type":"string","enum":["off","warn","block"]},"checkOrders":{"type":"boolean"},"checkBilling":{"type":"boolean"},"checkEmail":{"type":"boolean"},"checkPhone":{"type":"boolean"},"orderTags":{"type":"object","properties":{"enabled":{"type":"boolean"},"prefix":{"type":"string","maxLength":40},"format":{"type":"string","maxLength":40},"words":{"type":"object","properties":{"valid":{"type":"string","maxLength":40},"warn":{"type":"string","maxLength":40},"invalid":{"type":"string","maxLength":40},"unsupported":{"type":"string","maxLength":40},"skipped":{"type":"string","maxLength":40},"manual":{"type":"string","maxLength":40},"confirmed":{"type":"string","maxLength":40},"postBox":{"type":"string","maxLength":40},"emailValid":{"type":"string","maxLength":40},"emailInvalid":{"type":"string","maxLength":40},"emailUnknown":{"type":"string","maxLength":40},"phoneValid":{"type":"string","maxLength":40},"phoneInvalid":{"type":"string","maxLength":40},"phoneUnknown":{"type":"string","maxLength":40}},"required":["valid","warn","invalid","unsupported","skipped","manual","confirmed","postBox","emailValid","emailInvalid","emailUnknown","phoneValid","phoneInvalid","phoneUnknown"]}},"required":["enabled","prefix","format","words"],"x-avio-platforms":["shopware"]},"hold":{"type":"boolean"},"flowEvents":{"type":"boolean","x-avio-platforms":["shopware"]},"correctionLink":{"type":"boolean","x-avio-platforms":["shopware"]},"salesChannelIds":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^[0-9a-f]{32}$"},"x-avio-platforms":["shopware"]}},"required":["checkoutMode","checkOrders","checkBilling","checkEmail","checkPhone","orderTags","hold","flowEvents","correctionLink","salesChannelIds"]}]}},"required":["version","values"]},"RouteBody":{"type":"object","properties":{"provider":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"fallback":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"mode":{"type":"string","enum":["strict","balanced","loose"]},"enabled":{"type":"boolean"},"expected":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"fallback":{"type":"string"},"mode":{"type":"string"},"enabled":{"type":"boolean"}},"required":["provider","mode","enabled"]},{"type":"null"}]}},"required":["provider","mode","enabled","expected"]},"DeleteRouteBody":{"type":"object","properties":{"expected":{"type":"object","properties":{"provider":{"type":"string"},"fallback":{"type":"string"},"mode":{"type":"string"},"enabled":{"type":"boolean"}},"required":["provider","mode","enabled"]}},"required":["expected"]},"ConnectionReport":{"type":"object","properties":{"client":{"type":"string","minLength":1,"maxLength":100},"clientVersion":{"type":"string","minLength":1,"maxLength":100},"platformVersion":{"type":"string","minLength":1,"maxLength":100},"storeUrl":{"type":"string","maxLength":100,"format":"uri"}},"required":["client","clientVersion"]},"UninstallBody":{"type":"object","properties":{"keepData":{"type":"boolean"}}},"Address":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"province":{"type":"string"},"provinceCode":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"}},"required":["address1","city","countryCode"]},"VerdictDTO":{"type":"object","properties":{"status":{"type":"string","enum":["deliverable","corrected","ambiguous","invalid","unsupported","error"]},"provider":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"granularity":{"type":"string","enum":["subpremise","premise","street","locality","none"]},"changes":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["address1","address2","city","zip","province","provinceCode","countryCode"]},"from":{"type":"string"},"to":{"type":"string"},"kind":{"type":"string","enum":["alias","format","minor","major","inferred"]}},"required":["field","from","to","kind"]}},"missing":{"type":"array","items":{"type":"string","enum":["house_number","street","subpremise","postbox_number","zip","city"]}},"unverified":{"type":"array","items":{"type":"string","enum":["house_number","street","subpremise","postbox_number","zip","city"]}},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"suggestionsProvider":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]}},"required":["status","provider","granularity","changes","missing","unverified","suggestions"]},"Health":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"version":{"type":"string","const":"1"}},"required":["ok","version"]},"Faqs":{"type":"object","properties":{"tag":{"type":"string","enum":["shopify","shopware","woocommerce","website"]},"locale":{"type":"string","enum":["en","de","fr","es"]},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable; usable as a page anchor"},"title":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable within its topic"},"question":{"type":"string"},"answer":{"type":"string","description":"Plain text"},"link":{"type":"object","properties":{"href":{"type":"string","description":"An `https://` URL"},"label":{"type":"string"}},"required":["href","label"]}},"required":["id","question","answer"]}}},"required":["id","title","items"]}}},"required":["tag","locale","topics"]},"Changelog":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque id of the entry"},"date":{"type":"string","description":"ISO 8601 time the entry is dated"},"title":{"description":"Plain text; absent when staff gave none","type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["new","improved","fixed"]},"text":{"type":"string","description":"Plain text"},"platforms":{"type":"array","items":{"type":"string","enum":["shopify","woocommerce","shopware","api"]}}},"required":["kind","text","platforms"]}}},"required":["id","date","items"]}},"nextCursor":{"description":"Pass as `before` for older entries; absent on the last page","type":"string"}},"required":["entries"]},"Status":{"type":"object","properties":{"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When the alarm states were read"},"components":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable kebab-case: `api`, `order-checks`, `customer-emails`, `bulk-checks`, `<group>-<provider>` (e.g. `address-loqate`)"},"group":{"type":"string","enum":["service","address","email","phone"]},"name":{"type":"string"},"status":{"type":"string","enum":["operational","degraded","outage","unknown"],"description":"`unknown`: no recent data (no traffic) or the state could not be read; `degraded`: slow or partly failing"}},"required":["id","group","name","status"]}}},"required":["updatedAt","components"]},"TenantInfo":{"type":"object","properties":{"shopId":{"type":"string"},"tenantId":{"type":"string","deprecated":true,"description":"Use `shopId` (same value)."},"name":{"type":"string"},"platform":{"type":"string","enum":["woocommerce","shopware","custom"]},"storeDomain":{"type":"string"},"sandbox":{"type":"boolean"},"keyId":{"type":"string"},"apiVersion":{"type":"string","const":"1"}},"required":["shopId","tenantId","name","platform","sandbox","keyId","apiVersion"],"description":"The shop (store) and API key of the request. Named TenantInfo in v1."},"AddressCheck":{"type":"object","properties":{"decision":{"type":"string","enum":["valid","warn","invalid","skipped"]},"mode":{"type":"string","enum":["strict","balanced","loose"]},"addressHash":{"type":"string"},"verdict":{"allOf":[{"$ref":"#/components/schemas/VerdictDTO"},{"type":"object","properties":{"blocked":{"description":"The kind of delivery point the shop doesn't ship to (its delivery-point settings): the reason for `invalid`. Absent otherwise.","type":"string","enum":["poBox","parcelLocker"]}}}]},"issues":{"type":"array","items":{"type":"string","enum":["email_in_field","url_in_field","phone_in_field","zip_in_address1","missing_house_number","po_box","parcel_locker_without_number","parcel_locker","empty_required_field","po_box_blocked","parcel_locker_blocked","address_rule"]}},"rules":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["house_number","zip_format","too_long","po_box","parcel_locker_blocked","parcel_locker","email_invalid","email_disposable","address_rule"]},"field":{"type":"string","enum":["address1","address2","city","zip","province","email"]}},"required":["code","field"]}},"addressRules":{"description":"Every merchant address rule that matched. Absent when none did.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string","enum":["flag","block","replace","skip"]},"field":{"type":"string","enum":["address1","address2","city","zip","province"]}},"required":["id","action","field"]}},"rewrite":{"description":"The address after the merchant's replace rules: what was checked, and what `verdict` describes. Absent when no rule changed it.","$ref":"#/components/schemas/Address"}},"required":["decision","mode","addressHash","verdict","issues"]},"EmailCheckResult":{"type":"object","properties":{"result":{"type":"string","enum":["valid","invalid","unknown"]},"reason":{"type":"string","const":"syntax"},"disposable":{"type":"boolean"},"catchAll":{"type":"boolean"},"risky":{"type":"boolean"},"role":{"type":"boolean"},"suggestion":{"type":"string"}},"required":["result"]},"PhoneCheckResult":{"type":"object","properties":{"result":{"type":"string","enum":["valid","invalid","unknown"]},"e164":{"type":"string"},"lineType":{"type":"string"}},"required":["result"]},"OrderResult":{"type":"object","properties":{"orderId":{"type":"string"},"orderNumber":{"type":"string"},"decision":{"type":"string","enum":["valid","warn","invalid","skipped"]},"status":{"type":"string","enum":["validated","fixed","confirmed"]},"address":{"$ref":"#/components/schemas/Address"},"addressHash":{"type":"string"},"verdict":{"$ref":"#/components/schemas/VerdictDTO"},"issues":{"type":"array","items":{"type":"string","enum":["email_in_field","url_in_field","phone_in_field","zip_in_address1","missing_house_number","po_box","parcel_locker_without_number","parcel_locker","empty_required_field","po_box_blocked","parcel_locker_blocked","address_rule"]}},"billing":{"type":"object","properties":{"decision":{"type":"string","enum":["valid","warn","invalid","skipped"]},"verdict":{"$ref":"#/components/schemas/VerdictDTO"}},"required":["decision","verdict"]},"email":{"$ref":"#/components/schemas/EmailCheckResult"},"phone":{"$ref":"#/components/schemas/PhoneCheckResult"},"validatedAt":{"type":"string"},"correctedAt":{"type":"string"},"correctableUntil":{"type":"string"},"metered":{"type":"boolean"},"addressRules":{"description":"Every merchant address rule that matched. Absent when none did.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string","enum":["flag","block","replace","skip"]},"field":{"type":"string","enum":["address1","address2","city","zip","province"]}},"required":["id","action","field"]}},"rewrite":{"description":"The address after the merchant's replace rules: what was checked, and what `verdict` describes. Absent when no rule changed it.","$ref":"#/components/schemas/Address"}},"required":["orderId","decision","status","address","addressHash","verdict","issues","validatedAt","metered"]},"Deleted":{"type":"object","properties":{"deleted":{"type":"boolean","const":true}},"required":["deleted"]},"Usage":{"type":"object","properties":{"period":{"type":"string"},"currency":{"type":"string","const":"USD"},"addressChecks":{"type":"number"},"providerChecks":{"type":"number"},"orders":{"type":"number"},"freeOrders":{"type":"number","description":"The part of `orders` the store's one-time free checks covered: verified, never billed."},"repeatOrders":{"type":"number"},"accruedMicros":{"type":"number"},"emailChecks":{"type":"number"},"phoneChecks":{"type":"number"},"repeatSavedMicros":{"type":"number"},"accruedCounted":{"type":"boolean","description":"false while the month has no running charge total (nothing charged yet, or a month carried over from the old app): `accruedMicros` is 0 then."},"byProvider":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"`addressChecks` per provider that answered. Counts only."},"emailByProvider":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"Email checks of every source per provider that answered (`unknown`: no definite answer, `test`: the admin's comparison), counted since 2026-10-11."},"phoneByProvider":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"Phone checks as `emailByProvider`."},"meteredEmailChecks":{"type":"number"},"meteredPhoneChecks":{"type":"number"},"emailAccruedMicros":{"type":"number"},"phoneAccruedMicros":{"type":"number"}},"required":["period","currency","addressChecks","providerChecks","orders","freeOrders","repeatOrders","accruedMicros","emailChecks","phoneChecks","repeatSavedMicros","accruedCounted","byProvider","emailByProvider","phoneByProvider","meteredEmailChecks","meteredPhoneChecks","emailAccruedMicros","phoneAccruedMicros"]},"PlatformSettings":{"type":"object","properties":{"version":{"type":["string","null"]},"orders":{"type":"object","properties":{"ignoreAddress2":{"type":"boolean"},"correctionLock":{"description":"When customers can no longer change an order's address. `stage`: the fulfillment stage from which on (Shopify and Shopware only; absent on a save: the platform's default, which a read always shows); a shipped order always locks. `afterHours`: 1 to 1440 hours after the order was placed; absent: no time limit. A read always answers it.","type":"object","properties":{"stage":{"type":"string","enum":["requested","in_progress","partially_fulfilled","fulfilled"]},"afterHours":{"type":"integer","minimum":1,"maximum":1440}}},"validateBilling":{"x-avio-platforms":["shopify"],"type":"boolean"},"channels":{"x-avio-platforms":["shopify"],"description":"Sales channels whose orders Address Validation iO checks: a source name such as `web`, or an app's numeric id. A Shopify shop's read can still answer a value saved in the old app's form (`gid://shopify/App/<id>`), which a save refuses, until a save sends `channels`.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z0-9_-]+$"}},"orderTags":{"x-avio-platforms":["shopify"],"type":"object","properties":{"enabled":{"type":"boolean"},"prefix":{"type":"string","minLength":1},"format":{"type":"string","maxLength":40},"words":{"type":"object","properties":{"valid":{"type":"string","maxLength":40},"warn":{"type":"string","maxLength":40},"invalid":{"type":"string","maxLength":40},"unsupported":{"type":"string","maxLength":40},"skipped":{"type":"string","maxLength":40},"manual":{"type":"string","maxLength":40},"confirmed":{"type":"string","maxLength":40},"postBox":{"type":"string","maxLength":40},"emailValid":{"type":"string","maxLength":40},"emailInvalid":{"type":"string","maxLength":40},"emailUnknown":{"type":"string","maxLength":40},"phoneValid":{"type":"string","maxLength":40},"phoneInvalid":{"type":"string","maxLength":40},"phoneUnknown":{"type":"string","maxLength":40}},"required":["valid","warn","invalid","unsupported","skipped","manual","confirmed","postBox","emailValid","emailInvalid","emailUnknown","phoneValid","phoneInvalid","phoneUnknown"]}},"required":["enabled","prefix","format","words"]}},"required":["ignoreAddress2"],"x-avio-platforms":["shopify","woocommerce","shopware","custom"]},"deliveryPoints":{"type":"object","properties":{"default":{"type":"object","properties":{"poBox":{"type":"string","enum":["allow","block"]},"parcelLocker":{"type":"string","enum":["allow","block"]}},"required":["poBox","parcelLocker"]},"countries":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"poBox":{"type":"string","enum":["allow","block"]},"parcelLocker":{"type":"string","enum":["allow","block"]}},"required":["poBox","parcelLocker"]}}},"required":["default","countries"],"x-avio-platforms":["shopify","woocommerce","shopware","custom"]},"checkout":{"type":"object","properties":{"houseNumberCountries":{"type":"array","items":{"type":"string"}},"zipCountries":{"type":"array","items":{"type":"string"}},"maxAddressLength":{"type":"number"},"blockInvalidEmail":{"type":"boolean"},"blockDisposableEmail":{"type":"boolean"},"verifyEnabled":{"x-avio-platforms":["shopify"],"type":"boolean"},"blockOnInvalid":{"x-avio-platforms":["shopify"],"type":"boolean"},"autocompleteEnabled":{"x-avio-platforms":["shopify"],"description":"Address Validation iO's address suggestions in Shopify checkout (Plus only, also selected in the checkout editor). A read answers `false` until it is turned on.","type":"boolean"}},"required":["houseNumberCountries","zipCountries","maxAddressLength","blockInvalidEmail","blockDisposableEmail"],"x-avio-platforms":["shopify","woocommerce","shopware","custom"]},"addressRules":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string","enum":["address","address1","address2","city","zip","province"]},"match":{"type":"string","enum":["contains","word","equals","military","emoji","nonLatin","script","maxLength"]},"value":{"type":"string"},"max":{"type":"number"},"action":{"type":"string","enum":["flag","block","replace","skip"]},"replacement":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}}},"required":["id","field","match","action","countries"]}}},"required":["rules"],"x-avio-platforms":["shopify","woocommerce","shopware","custom"]},"contact":{"type":"object","properties":{"email":{"type":"object","properties":{"provider":{"type":"string"},"fallback":{"type":"string"}},"required":["provider"]},"phone":{"type":"object","properties":{"provider":{"type":"string"},"fallback":{"type":"string"}},"required":["provider"]}},"required":["email","phone"],"x-avio-platforms":["shopify","woocommerce","shopware","custom"]},"analytics":{"type":"object","properties":{"costPerFailedDeliveryMicros":{"type":"integer","minimum":0,"maximum":10000000000},"calculator":{"x-avio-platforms":["shopify"],"type":"object","properties":{"orders":{"type":"integer","minimum":0,"maximum":10000000},"badRate":{"type":"number","minimum":0,"maximum":100},"preventRate":{"type":"number","minimum":0,"maximum":100},"mode":{"type":"string","enum":["basic","advanced"]},"lines":{"type":"object","properties":{"returns":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":10000},"share":{"type":"number","minimum":0,"maximum":100}},"required":["value","share"]},"support":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":10000},"share":{"type":"number","minimum":0,"maximum":100}},"required":["value","share"]},"reshipping":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":10000},"share":{"type":"number","minimum":0,"maximum":100}},"required":["value","share"]},"restocking":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":10000},"share":{"type":"number","minimum":0,"maximum":100}},"required":["value","share"]}},"required":["returns","support","reshipping","restocking"]}},"required":["badRate","preventRate","mode","lines"]},"version":{"type":["string","null"]}},"required":["costPerFailedDeliveryMicros","version"],"x-avio-platforms":["shopify","woocommerce","shopware","custom"]},"store":{"description":"The store's own settings in its platform's shape, for the platforms in x-avio-platforms: when the store checks and what it does with the answer. WooCommerce: checkout mode, order, billing, email and phone checks, holds, the My Account check. Shopware: the same checks plus order tags, flow events, the correction link and the sales channels.","x-avio-platforms":["woocommerce","shopware"],"anyOf":[{"type":"object","properties":{"checkoutMode":{"type":"string","enum":["off","warn","block"]},"checkOrders":{"type":"boolean"},"checkBilling":{"type":"boolean"},"checkEmail":{"type":"boolean"},"checkPhone":{"type":"boolean"},"hold":{"type":"boolean"},"accountCheck":{"type":"boolean","x-avio-platforms":["woocommerce"]},"version":{"type":["string","null"]}},"required":["checkoutMode","checkOrders","checkBilling","checkEmail","checkPhone","hold","accountCheck","version"]},{"type":"object","properties":{"checkoutMode":{"type":"string","enum":["off","warn","block"]},"checkOrders":{"type":"boolean"},"checkBilling":{"type":"boolean"},"checkEmail":{"type":"boolean"},"checkPhone":{"type":"boolean"},"orderTags":{"type":"object","properties":{"enabled":{"type":"boolean"},"prefix":{"type":"string","minLength":1},"format":{"type":"string","maxLength":40},"words":{"type":"object","properties":{"valid":{"type":"string","maxLength":40},"warn":{"type":"string","maxLength":40},"invalid":{"type":"string","maxLength":40},"unsupported":{"type":"string","maxLength":40},"skipped":{"type":"string","maxLength":40},"manual":{"type":"string","maxLength":40},"confirmed":{"type":"string","maxLength":40},"postBox":{"type":"string","maxLength":40},"emailValid":{"type":"string","maxLength":40},"emailInvalid":{"type":"string","maxLength":40},"emailUnknown":{"type":"string","maxLength":40},"phoneValid":{"type":"string","maxLength":40},"phoneInvalid":{"type":"string","maxLength":40},"phoneUnknown":{"type":"string","maxLength":40}},"required":["valid","warn","invalid","unsupported","skipped","manual","confirmed","postBox","emailValid","emailInvalid","emailUnknown","phoneValid","phoneInvalid","phoneUnknown"]}},"required":["enabled","prefix","format","words"],"x-avio-platforms":["shopware"]},"hold":{"type":"boolean"},"flowEvents":{"type":"boolean","x-avio-platforms":["shopware"]},"correctionLink":{"type":"boolean","x-avio-platforms":["shopware"]},"salesChannelIds":{"maxItems":100,"type":"array","items":{"type":"string","pattern":"^[0-9a-f]{32}$"},"x-avio-platforms":["shopware"]},"version":{"type":["string","null"]}},"required":["checkoutMode","checkOrders","checkBilling","checkEmail","checkPhone","orderTags","hold","flowEvents","correctionLink","salesChannelIds","version"]}]},"holds":{"x-avio-platforms":["shopify"],"type":"object","properties":{"fulfillmentHold":{"type":"object","properties":{"enabled":{"type":"boolean"},"releaseAfterHours":{"type":"integer","minimum":1,"maximum":720},"alertBeforeHours":{"type":"integer","minimum":0,"maximum":719},"alertIntervalHours":{"type":"integer","minimum":1,"maximum":168}},"required":["enabled","releaseAfterHours"]}},"required":["fulfillmentHold"],"description":"Shopify shops only: hold the fulfillment of an order whose address is invalid, released on correction or after `releaseAfterHours` (1 to 720). `alertBeforeHours` (0 to 719, absent = 12): email the shop that many hours before the release about held orders the customer hasn't fixed yet; 0 or at least `releaseAfterHours` = no email. `alertIntervalHours` (1 to 168, absent = 6): at most one such email per that many hours; an order may be listed up to that much earlier than `alertBeforeHours`. Needs the Fulfillment holds package; without it a save keeps the stored values."},"emails":{"x-avio-platforms":["shopify"],"type":"object","properties":{"customerEmails":{"type":"object","properties":{"enabled":{"type":"boolean"},"reminderHours":{"maxItems":5,"type":"array","items":{"type":"integer","minimum":1,"maximum":720}},"replyTo":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"merchantCopy":{"type":"boolean"},"linkTarget":{"type":"string","enum":["order-status","correction-page"]},"proxyPath":{"type":"string","maxLength":41}},"required":["enabled","reminderHours","merchantCopy"]}},"required":["customerEmails"],"description":"Shopify shops only: the correction request emails to the customer. `reminderHours`: at most 5 reminders, each 1 to 720 hours after the request. `replyTo`: where replies go; absent, the shop's email when the emails come from Address Validation iO's sender. `merchantCopy`: Bcc the shop's email on the request (not the reminders). `linkTarget`: where the email's link leads, `order-status` (the order status page, Address Validation iO's block) or `correction-page` (Address Validation iO's own page on the shop's app proxy); absent, by the shop's customer accounts: classic accounts get `correction-page`, anything else `order-status`. `proxyPath`: `/<a|apps|community|tools>/<subpath>`, only for a merchant who renamed Address Validation iO's app proxy in Shopify; absent, `/a/address-validation`."},"accounts":{"x-avio-platforms":["shopify"],"type":"object","properties":{"customerAccount":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}},"required":["customerAccount"],"description":"Shopify shops only: the customer account extensions (the order list banner, the address check page, saved addresses)."},"choices":{"type":"object","properties":{"zipCountries":{"type":"array","items":{"type":"string"}},"contactProviders":{"type":"object","properties":{"email":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"priceMicros":{"type":"number"}},"required":["id","priceMicros"]}},"phone":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"priceMicros":{"type":"number"}},"required":["id","priceMicros"]}}},"required":["email","phone"]}},"required":["zipCountries","contactProviders"]}},"required":["version","orders","deliveryPoints","checkout","addressRules","contact","analytics","choices"]},"PlatformStats":{"type":"object","properties":{"days":{"anyOf":[{"type":"number","const":7},{"type":"number","const":30},{"type":"number","const":90},{"type":"number","const":365}]},"range":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"bucket":{"type":"string","enum":["day","month"]}},"required":["from","to","bucket"]},"labels":{"type":"array","items":{"type":"string"}},"series":{"type":"object","properties":{"checks":{"type":"array","items":{"type":"number"}},"valid":{"type":"array","items":{"type":"number"}},"warn":{"type":"array","items":{"type":"number"}},"invalid":{"type":"array","items":{"type":"number"}},"skipped":{"type":"array","items":{"type":"number"}},"corrected":{"type":"array","items":{"type":"number"}},"confirmed":{"type":"array","items":{"type":"number"}},"emailsChecked":{"type":"array","items":{"type":"number"}},"phonesChecked":{"type":"array","items":{"type":"number"}},"savingsMicros":{"type":"array","items":{"type":"number"}},"emailsSent":{"type":"array","items":{"type":"number"}}},"required":["checks","valid","warn","invalid","skipped","corrected","confirmed","emailsChecked","phonesChecked","savingsMicros","emailsSent"]},"totals":{"$ref":"#/components/schemas/StatsTotals"},"previous":{"anyOf":[{"$ref":"#/components/schemas/StatsTotals"},{"type":"null"}]},"changes":{"type":"object","properties":{"checks":{"type":["number","null"]},"validRate":{"type":["number","null"]},"corrected":{"type":["number","null"]},"confirmed":{"type":["number","null"]},"savings":{"type":["number","null"]},"emailsSent":{"type":["number","null"]}},"required":["checks","validRate","corrected","confirmed","savings","emailsSent"]},"countries":{"type":"array","items":{"type":"object","properties":{"countryCode":{"type":"string"},"checks":{"type":"number"}},"required":["countryCode","checks"]}},"costPerFailedDeliveryMicros":{"type":"number"},"accruedSince":{"type":["string","null"]},"metering":{"type":"string","enum":["accrual","shopify-billing"],"description":"`accrual`: the charged prices accrue and are not invoiced yet. `shopify-billing`: Shopify usage records bill them."},"countersSince":{"type":"string","description":"The UTC day from which the shop's daily charges are counted: the stats' `accruedMicros`, and with it the savings, leave out the days before it."},"daily":{"description":"With `daily=1`: the days of `range` that have counters, oldest first. A day without any has no entry.","type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"checks":{"type":"number"},"bySource":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"The day's checks per source: `checkout`, `order`, `admin` (bulk and Flow included), `correction`. Counted since 2026-10-06; a check from a test, the widget or an A/B arm has none."}},"required":["day","checks","bySource"]}}},"required":["days","range","labels","series","totals","previous","changes","countries","costPerFailedDeliveryMicros","accruedSince","metering","countersSince"]},"StatsTotals":{"type":"object","properties":{"checks":{"type":"number"},"valid":{"type":"number"},"warn":{"type":"number"},"invalid":{"type":"number"},"skipped":{"type":"number"},"corrected":{"type":"number"},"confirmed":{"type":"number"},"ordersFlagged":{"type":"number"},"verifiedOrders":{"type":"number"},"emailsChecked":{"type":"number"},"emailsInvalid":{"type":"number"},"emailsBounced":{"type":"number"},"phonesChecked":{"type":"number"},"phonesInvalid":{"type":"number"},"accruedMicros":{"type":"number"},"failedDeliveryCostAvoidedMicros":{"type":"number"},"savingsMicros":{"type":"number"},"emailsSent":{"type":"number"},"ordersEmailed":{"type":"number"},"held":{"type":"number"},"released":{"type":"number"},"byCountry":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"Address checks per country, every country (`??`: unknown)."},"byProvider":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"Provider calls per provider, fallbacks and the admin's tests included. Counts only."}},"required":["checks","valid","warn","invalid","skipped","corrected","confirmed","ordersFlagged","verifiedOrders","emailsChecked","emailsInvalid","emailsBounced","phonesChecked","phonesInvalid","accruedMicros","failedDeliveryCostAvoidedMicros","savingsMicros","emailsSent","ordersEmailed","held","released","byCountry","byProvider"]},"StatsSources":{"type":"object","properties":{"range":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","bucket"]},"labels":{"type":"array","items":{"type":"string"}},"series":{"type":"object","properties":{"checkout":{"type":"array","items":{"type":"number"}},"admin":{"type":"array","items":{"type":"number"}},"order":{"type":"array","items":{"type":"number"}},"correction":{"type":"array","items":{"type":"number"}}},"required":["checkout","admin","order","correction"]},"sourcesSince":{"description":"Set when `range.from` is before this day: the sources are counted from then on, and earlier checks have none.","type":["string","null"]}},"required":["range","labels","series","sourcesSince"]},"UsagePrices":{"type":"object","properties":{"verifiedOrderMicros":{"type":"number"},"verifiedOrderFrom":{"type":"boolean"},"includedPerMonth":{"type":"number"},"repeatDiscountPercent":{"type":"number"},"emailCheckMicros":{"type":"number"},"phoneCheckMicros":{"type":"number"}},"required":["verifiedOrderMicros","verifiedOrderFrom","includedPerMonth","repeatDiscountPercent","emailCheckMicros","phoneCheckMicros"]},"UsageWithPrices":{"type":"object","properties":{"period":{"type":"string"},"currency":{"type":"string","const":"USD"},"addressChecks":{"type":"number"},"providerChecks":{"type":"number"},"orders":{"type":"number"},"freeOrders":{"type":"number","description":"The part of `orders` the store's one-time free checks covered: verified, never billed."},"repeatOrders":{"type":"number"},"accruedMicros":{"type":"number"},"emailChecks":{"type":"number"},"phoneChecks":{"type":"number"},"repeatSavedMicros":{"type":"number"},"accruedCounted":{"type":"boolean","description":"false while the month has no running charge total (nothing charged yet, or a month carried over from the old app): `accruedMicros` is 0 then."},"byProvider":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"`addressChecks` per provider that answered. Counts only."},"emailByProvider":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"Email checks of every source per provider that answered (`unknown`: no definite answer, `test`: the admin's comparison), counted since 2026-10-11."},"phoneByProvider":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"Phone checks as `emailByProvider`."},"meteredEmailChecks":{"type":"number"},"meteredPhoneChecks":{"type":"number"},"emailAccruedMicros":{"type":"number"},"phoneAccruedMicros":{"type":"number"},"prices":{"$ref":"#/components/schemas/UsagePrices"},"metering":{"type":"string","enum":["accrual","shopify-billing"],"description":"`accrual`: the charged prices accrue and are not invoiced yet. `shopify-billing`: Shopify usage records bill them."},"countersSince":{"type":"string","description":"The UTC day from which the shop's daily charges are counted: the stats' `accruedMicros`, and with it the savings, leave out the days before it."}},"required":["period","currency","addressChecks","providerChecks","orders","freeOrders","repeatOrders","accruedMicros","emailChecks","phoneChecks","repeatSavedMicros","accruedCounted","byProvider","emailByProvider","phoneByProvider","meteredEmailChecks","meteredPhoneChecks","emailAccruedMicros","phoneAccruedMicros","prices","metering","countersSince"]},"UsageMonths":{"type":"object","properties":{"months":{"type":"array","items":{"$ref":"#/components/schemas/Usage"}},"metering":{"type":"string","enum":["accrual","shopify-billing"],"description":"`accrual`: the charged prices accrue and are not invoiced yet. `shopify-billing`: Shopify usage records bill them."},"countersSince":{"type":"string","description":"The UTC day from which the shop's daily charges are counted: the stats' `accruedMicros`, and with it the savings, leave out the days before it."}},"required":["months","metering","countersSince"]},"PlatformRoutes":{"type":"object","properties":{"routes":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"fallback":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"mode":{"type":"string","enum":["strict","balanced","loose"]},"enabled":{"type":"boolean"},"countryCode":{"type":"string"},"source":{"type":"string","enum":["recommended","custom"]}},"required":["provider","mode","enabled","countryCode","source"]}},"stored":{"type":"boolean"},"followsRecommended":{"type":"boolean"},"recommended":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"fallback":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"mode":{"type":"string","enum":["strict","balanced","loose"]},"enabled":{"type":"boolean"},"countryCode":{"type":"string"}},"required":["provider","mode","enabled","countryCode"]}},"choices":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"countries":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string","const":"*"}]}},"required":["id","countries"]}},"modes":{"type":"array","items":{"type":"string","enum":["strict","balanced","loose"]}}},"required":["countries","providers","modes"]}},"required":["routes","stored","followsRecommended","recommended","choices"]},"LogRow":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"kind":{"type":"string","enum":["validation","address","correction","email","phone","hold","tag","flow","billing","settings","app","error"]},"level":{"type":"string","enum":["info","warning","error"]},"code":{"type":"string"},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]}},"orderId":{"type":"string"},"orderName":{"type":"string"},"source":{"type":"string","enum":["checkout","order-created","order-updated","admin","bulk","flow","customer","widget-address","test","ab-test"]},"decision":{"type":"string","enum":["valid","warn","invalid","skipped"]},"previousDecision":{"type":"string","enum":["valid","warn","invalid","skipped"]},"countryCode":{"type":"string"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"status":{"type":"string"},"latencyMs":{"type":"number"}},"required":["provider","status","latencyMs"]}},"cached":{"type":"boolean"},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["merchant","customer","avio","system","platform-api"]}},"required":["type"]},"changes":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"}},"required":["field"]}},"recipientChanged":{"type":"boolean"},"tags":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}}},"required":["added","removed"]}},"required":["id","at","kind","level","code"]},"LogPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LogRow"}},"page":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasNext":{"type":"boolean"},"hasPrevious":{"type":"boolean"}},"required":["cursor","hasNext","hasPrevious"]}},"required":["items","page"]},"OrderLogs":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LogRow"}}},"required":["items"]},"Capabilities":{"type":"object","properties":{"apiVersion":{"type":"string","const":"1"},"shop":{"type":"object","properties":{"shopId":{"type":"string"},"platform":{"type":"string","enum":["shopify","woocommerce","shopware","custom"]},"sandbox":{"type":"boolean"},"validating":{"type":"boolean"},"installation":{"type":"object","properties":{"state":{"type":"string","enum":["pending","connected","uninstalled","suspended"]},"proof":{"type":"string","enum":["shopify-oauth","shopware-app","api-key"]},"connectedAt":{"type":"string"},"lastSeenDay":{"type":"string"},"client":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}},"required":["name","version"]},"platformVersion":{"type":"string"}},"required":["state","proof"]}},"required":["shopId","platform","sandbox","validating","installation"]},"plan":{"type":"object","properties":{"id":{"type":"string","enum":["payg","starter","business","pro","enterprise"]},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["fulfillmentHolds","flow","insights","headlessWidget"]},"active":{"type":"boolean"}},"required":["id","active"]}},"addons":{"type":"object","properties":{"email":{"type":"boolean"},"phone":{"type":"boolean"}},"required":["email","phone"]}},"required":["id","packages","addons"]},"checks":{"type":"object","properties":{"address":{"type":"object","properties":{"contexts":{"type":"array","items":{"type":"string","enum":["checkout","account","other","test"]}},"modes":{"type":"array","items":{"type":"string","enum":["strict","balanced","loose"]}},"countries":{"type":"array","items":{"type":"string"}},"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["loqate","google","postcode-eu","smarty","sandbox"]},"name":{"type":"string"},"countries":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string","const":"*"}]},"capabilities":{"type":"array","items":{"type":"string","enum":["corrections","premise","unit","missingUnit","poBox"]}},"region":{"type":"string","enum":["UK/EU","Global","EU"]},"priceMicros":{"type":"number"}},"required":["id","name","countries","capabilities","region","priceMicros"]}},"deliveryPointKinds":{"type":"array","items":{"type":"string","enum":["poBox","parcelLocker"]}},"zipRuleCountries":{"type":"array","items":{"type":"string"}}},"required":["contexts","modes","countries","providers","deliveryPointKinds","zipRuleCountries"]},"email":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string","enum":["syntax","domain","mailbox","catchAll","disposable","role","lineType","carrier"]}},"priceMicros":{"type":"number"}},"required":["id","name","capabilities","priceMicros"]}}},"required":["providers"]},"phone":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string","enum":["syntax","domain","mailbox","catchAll","disposable","role","lineType","carrier"]}},"priceMicros":{"type":"number"}},"required":["id","name","capabilities","priceMicros"]}}},"required":["providers"]}},"required":["address","email","phone"]},"prices":{"$ref":"#/components/schemas/UsagePrices"},"settings":{"type":"object","properties":{"areas":{"type":"array","items":{"type":"string","enum":["orders","delivery-points","checkout","address-rules","contact","analytics","store","holds","emails","accounts","general","widget","default-mode"]}},"storeFields":{"type":"array","items":{"type":"string"}}},"required":["areas"]},"features":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["address-check","checkout-check","checkout-rules","address-rules","order-check","email-check","phone-check","hold","order-tags","correction","customer-emails","flow","bulk-check","ab-tests","insights","headless-widget"]},"execution":{"type":"string","enum":["avio","client","native","unsupported"]},"available":{"type":"boolean"},"gate":{"type":"object","properties":{"package":{"type":"string","enum":["fulfillmentHolds","flow","insights","headlessWidget"]},"addon":{"type":"string","enum":["email","phone"]}}},"reason":{"type":"string","enum":["platform","planned","needs_invoicing"]},"config":{"type":"array","items":{"type":"object","properties":{"area":{"type":"string","enum":["orders","delivery-points","checkout","address-rules","contact","analytics","store","holds","emails","accounts","general","widget","default-mode"]},"fields":{"type":"array","items":{"type":"string"}}},"required":["area","fields"]}}},"required":["id","execution","available"]}}},"required":["apiVersion","shop","checks","prices","settings","features"]},"UninstallResult":{"type":"object","properties":{"state":{"type":"string","const":"uninstalled"},"keepData":{"type":"boolean"}},"required":["state","keepData"]},"Banners":{"type":"object","properties":{"banners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tone":{"type":"string","enum":["info","success","warning","critical"]},"dismissible":{"type":"boolean"},"endAt":{"description":"ISO time the banner ends; absent: until unpublished","type":"string"},"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"bold":{"type":"boolean","const":true},"italic":{"type":"boolean","const":true},"code":{"type":"boolean","const":true}},"required":["text"]}}},"required":["type","content"]},{"type":"object","properties":{"type":{"type":"string","const":"list"},"ordered":{"type":"boolean"},"items":{"type":"array","items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"bold":{"type":"boolean","const":true},"italic":{"type":"boolean","const":true},"code":{"type":"boolean","const":true}},"required":["text"]}}}},"required":["type","ordered","items"]},{"type":"object","properties":{"type":{"type":"string","const":"actions"},"actions":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["link","button"]},"label":{"type":"string"},"url":{"type":"string","description":"`https://…` (open in a new tab), `mailto:…`, or the host's own page: Shopify `/app/…`, WooCommerce `admin.php?page=avio&tab=…` (relative to wp-admin), Shopware the iframe page path (`/settings`) to sign with the session"}},"required":["kind","label","url"]}}},"required":["type","actions"]}]}},"html":{"type":"string","description":"The blocks as plain HTML, every value escaped (one `h3` level, action rows as `<p>` of links, buttons with class `button`)"}},"required":["id","tone","dismissible","blocks","html"]}}},"required":["banners"]},"BannerDismissed":{"type":"object","properties":{"dismissed":{"type":"boolean","const":true}},"required":["dismissed"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}}},"required":["error"]}}}}