Zum Inhalt springen
Address Validation iO

Diese Dokumentation gibt es nur auf Englisch.

Headless-Widget

Headless widget

Embed the Address Validation iO widget on a headless Shopify storefront so signed-in customers can fix order addresses and get address-book checks.

The headless widget is a small script for Shopify stores with their own storefront, for example Hydrogen or Next.js. On your account pages, signed-in customers see which orders need an address check and fix them right there. It can also check addresses in your address book forms before they are saved.

The widget does not cover checkout: Address Validation iO's checkout checks run in Shopify's own checkout. A regular Shopify theme doesn't need the widget.

Before you start

  • The Address Validation iO Shopify app is installed.
  • Your plan includes the Headless widget package. See Pricing and Plans.
  • In the app, go to Settings → Customer accounts & headless → Set up the headless widget and:
    1. Generate secret. It is shown only once. Store it on your storefront's server as AVIO_WIDGET_SECRET. Never put it in browser code.
    2. Add your storefront under Allowed origins, one per line, for example https://shop.example.com (at most 10). http:// works only for localhost.
    3. Turn on the widget.

Every widget needs a token that your server signs for the signed-in customer. See Tokens.

Add the script

Add the script once, for example in your layout:

HTML
<script src="https://widget.address-validation.io/widget/v1/avio.js" async></script>

The script mounts every element with a data-avio-widget attribute, including elements added later by client-side navigation. When data-token or data-order-id changes on an element, the widget remounts with the new values.

Widget modes

Set the mode with data-avio-widget.

orders: account overview

A notice such as "Your order #1234 needs your attention", with a list of the affected orders. It renders nothing when no order needs attention.

HTML
<div data-avio-widget="orders" data-token="CUSTOMER_TOKEN" data-order-url="/account/orders/{id}"></div>

data-order-url is the link to your own order page. Keep {id} as written: the widget fills in the order id. It must be a relative or http(s) URL.

order: order details

Place it on your order page. The customer sees the current address and hints, and can choose Use this address for a suggestion, Edit your address or My address is correct. A saved change updates the order's shipping address, checks it again and releases Address Validation iO's fulfillment hold. Changes are no longer possible once the order is fulfilled or in progress.

HTML
<div data-avio-widget="order" data-order-id="ORDER_ID" data-token="ORDER_TOKEN"></div>

data-order-id is the numeric Shopify order id or its gid://shopify/Order/… GID. Use an order-scoped token for this element. If Address Validation iO never checked the order, the element stays empty.

address-form: address book

Attach the widget to your own address form. When the customer saves:

  • a valid address is saved right away;
  • an address that needs a look shows suggestions (Use this address fills the fields and submits) or lets the customer keep their address;
  • an invalid address shows the issue and blocks the save, with Use my address anyway unless the country's mode is strict.

If the check isn't possible (network error, timeout, limit reached, expired token), the form is saved as entered. The widget is guidance, not enforcement: if you must enforce valid addresses, check again on your server before saving.

HTML
<form id="address-form">…</form>
<div
  data-avio-widget="address-form"
  data-token="CUSTOMER_TOKEN"
  data-avio-form="#address-form"
  data-field-map='{"address1":"street","zip":"postalCode"}'
></div>
  • data-avio-form: a CSS selector for the form. Without it, the widget uses the <form> around the element, or the one inside it.
  • data-field-map: JSON that maps Address Validation iO's field names to your form's input names. The defaults are address1, address2, city, zip, province, provinceCode, countryCode (or country), firstName, lastName, company and phone.

A form without a street, a city or a two-letter country code isn't checked and saves normally, so a missing mapping never blocks the form.

Address-book checks are not orders: they aren't billed per check and appear in your Logs as "Address form". They are limited to 20 provider checks per customer per hour.

Attributes

Attribute On Meaning
data-avio-widget element orders, order or address-form
data-token element or script The signed token. A data-token on the script tag is the default for every element.
data-order-id order The Shopify order id
data-order-url orders Link to your order page, with {id} as placeholder
data-avio-form address-form CSS selector of the form
data-field-map address-form JSON map of field names
data-locale element Language of the texts, for example de. Defaults to <html lang>, then the browser's language.
data-manual script Turns off automatic mounting; call AvioWidget.mount() yourself.

Events

Both events bubble, so you can listen on the element or on document.

Event Fired on detail
avio:order-updated the order element The updated order, after the customer saved a correction or confirmed the address.
avio:address-result the form (address-form) The check's result, or { decision: "skipped", error } when the check failed (error is the HTTP status, 0 for a network error).

Use avio:order-updated to refresh the parts of your page that show the order's address or status:

TypeScript
document.addEventListener("avio:order-updated", (event) => {
  const order = (event as CustomEvent).detail;
  console.log("Address updated", order);
  // e.g. router.refresh() in Next.js
});

JavaScript API

The script defines window.AvioWidget:

Function What it does
mount(element) Mounts one element (with data-manual, or after you add it).
scan() Mounts every [data-avio-widget] element on the page.
attachAddressForm(form, { token, fieldMap?, host?, locale? }) Same as the address-form mode, from code. Returns { detach() }. host is where the result panel renders.
validateAddress(address, { token, locale? }) Only the check, for frameworks that manage forms themselves. Returns a promise with the result (decision is valid, warn, invalid or skipped); it rejects with error.status on HTTP and network errors.
TypeScript
const { detach } = window.AvioWidget.attachAddressForm(formElement, {
  token,
  fieldMap: { address1: "street" },
});

const result = await window.AvioWidget.validateAddress(address, { token });

Look and texts

The widget renders in a Shadow DOM, so your page styles don't leak in. It uses the Design settings in the app (banner tones, suggestions, accent color) and your order-status texts in every language you turned on. To override the look, set CSS custom properties on the widget element:

Property Controls
--avio-accent Buttons and accent color
--avio-accent-text Text on the accent color
--avio-accent-ink Accent-colored text and the focus outline
--avio-radius Corner radius
--avio-border Border color
--avio-info-background, --avio-warning-background, --avio-critical-background Background per tone (also -color and -dot)

When the widget shows nothing, the element gets the data-avio-empty attribute and is hidden.

Troubleshooting

The widget shows nothing

The widget is off, no secret was generated, the app was uninstalled or the package is missing. It also stays empty when no order needs attention, or when Address Validation iO never checked the order.

"Your session has expired. Please reload the page."

The token expired or the secret was rotated. Reloading the page gets a new token from your server.

The browser blocks the request

Your site isn't in Allowed origins, or it uses http:// instead of https://.