=== Address Autofill for FluentCart ===
Contributors: fluentcart
Tags: fluentcart, checkout, japan, postal code, address
Requires at least: 5.8
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later

Fills the state, city and street address from the postal code at FluentCart checkout. Ships with a Japanese provider.

== Description ==

Japanese checkouts are normally driven by the 7-digit postal code: the shopper
types `100-0001` and expects the prefecture, municipality and town to appear.
This add-on does exactly that for FluentCart, the way Japanese shoppers already
expect from other stores.

It fills three fields on both the billing and shipping address:

* State / Prefecture
* City / Municipality
* Street address (town area)

The prefecture is written through FluentCart's own state selector, so shipping
and tax recalculate exactly as they do when a shopper picks a prefecture by
hand. The Apt/suite field is never touched, and a building or room number the
shopper has already typed into the street field is never overwritten.

= Other countries =

Japan is the only built-in provider. Any other country — or your own copy of the
Japan Post postal file instead of the public lookup service — can be supplied
with two filters:

`add_filter('fluent_cart/checkout/postcode_autofill_countries', function ($countries) {
    $countries[] = 'DE';
    return $countries;
});`

`add_filter('fluent_cart/checkout/postcode_lookup', function ($address, $context) {
    // $context['postcode'], $context['country']
    return ['state' => 'JP13', 'city' => 'Chiyoda', 'address_1' => 'Chiyoda'];
}, 10, 2);`

The `state` value may be either a FluentCart state code (`JP13`) or the state's
name (`Tokyo`) — a name is resolved to its code, and a name matching no known
state is dropped rather than guessed at.

== Third-party services ==

With the built-in Japanese provider enabled, postal codes are looked up through
zipcloud (https://zipcloud.ibsnet.co.jp/), a free public mirror of the Japan
Post postal file. Only the postal code the shopper typed is sent; nothing else
about them is. Results are cached for one week, so a given postal code is only
ever looked up once. Terms: https://zipcloud.ibsnet.co.jp/rule

Hook `fluent_cart/checkout/postcode_lookup` to use a local dataset instead and
no external request is made at all.

== Requirements ==

FluentCart must be installed and active. The State field must be enabled under
FluentCart → Settings → Checkout Fields, or there is nowhere to put the
prefecture.

== Changelog ==

= 1.0.0 (Nov 17, 2026) =
* Initial release: Japanese postal code address autofill.
