Address validation & geocoding for commercetools.
Two packages — React widgets for the storefront and a server-side API Extension handler — so Cart updates are gated end-to-end. Designed for Alokai, commercetools Frontend, or a custom Next.js BFF. MIT licence.
Two packages, not one
Storefront widget + server-side gate.
@acuris-geo/commercetools-checkout
React widgets for the storefront
<AcurisAddressInput> typeahead and
<AcurisAddressValidator> render-prop, emitting
commercetools BaseAddress-shaped objects (ISO-2
country, split streetName /
streetNumber, postalCode). Boundary
mappers (toBaseAddress,
iso2ToIso3) hide the wire-format translation.
@acuris-geo/commercetools-extension
API Extension handler for Cart updates
A Node handler for commercetools's
API Extension on Cart:Update. Validates every
setShippingAddress action server-side and either
rewrites the address to Acuris's standardized
form or rejects with InvalidInput.
Closes the storefront-only bypass that bots and partner code can
exploit.
Quick start
Install. Wire. Done.
What it does
Drop-in pieces.
ISO-2 country codes
commercetools speaks "DE" / "US" / "NL";
Acuris speaks "deu" / "usa" / "nld".
The connector translates in exactly one place — your proxy route — via the
exported iso2ToIso3 helper.
BaseAddress in, BaseAddress out
suggestionToBaseAddress and toBaseAddress
give you back a clean BaseAddress ready to hand
straight to cart.setShippingAddress(...). Identity
fields (name, phone, company) are preserved verbatim.
Three handler modes
Extension handler runs in rewrite (replace with standardized form), reject (abort below confidence threshold), or annotate (placeholder for Custom Field round-trip in v0.2).
Multi-runtime adapters
buildLambdaHandler for AWS Lambda,
buildNodeHttpHandler for Express / raw Node http,
buildExtensionHandler for generic async runtimes.
Same processExtension core under each.
Framework-agnostic React
Works under Alokai, commercetools Frontend (ex-Frontastic), or a
custom Next.js BFF. The widget doesn't monkey-patch
@commercetools/platform-sdk — you keep your existing
cart layer.
Fail-open by default
Acuris-side network or 5xx failures don't block Cart updates — inbound action stands. Strict fail-closed mode coming in 0.2 for compliance-driven deployments.
Architecture
Three pieces, two trust boundaries.
Browser Your backend Acuris
───────── ───────── ─────────
<AcurisAddressInput> ──► /api/acuris/suggest ──► GET /suggest
<AcurisAddressValidator> ─► /api/acuris/validate ──► POST /validate
(acuris-av-sdk + (api.acuris-geo.com)
ACURIS_API_KEY +
iso2ToIso3)
commercetools API Extension on Cart:Update
──► your-lambda/url ──► POST /validate
(acuris-av-sdk +
ACURIS_API_KEY)
The storefront component guides the buyer; the API Extension guarantees the result. Backend code, partner integrations, and CSV bulk imports all hit the extension and can't bypass validation. Full details in the architecture doc and integration guide.
In the Connect Marketplace
How Acuris compares to other commercetools address-validation listings.
| Property | Acuris | Loqate | Avalara /check-address |
|---|---|---|---|
| Country coverage | 240+ | 240+ | ~100 (US/CA-led) |
| API Extension handler | Yes (rewrite + reject) | Yes | Yes |
| Storefront React widget | Yes (open-source) | Yes (proprietary) | No |
| Open-source connector | MIT | Closed | Closed |
| EU data residency | Yes (German GmbH) | Per-tenant | US-default |
| EUDI Wallet ready | Yes (live verifier) | — | — |
See it run
A working Next.js storefront, deployed.
Running commercetools?
The connector is open-source under MIT — clone and run today. Acuris API keys come with a free Dev bundle: 1,000 address validations and 1,000 geocoding lookups (plus email and phone validation credits), valid for 4 weeks.