Everything here is read from the code of Gatemi EU VAT Number 1.0.2 and Gatemi VAT Number for WooCommerce 1.0.0. Items marked Full edition exist only in the paid plugin.
Filters and actions
gmvat_exempt (filter) — both editions
Decides whether one checkout is exempt, after the four built-in conditions.
apply_filters( 'gmvat_exempt', bool $exempt, array $check, string $country );
$exempt— the plugin's answer.$check— the VIES result (see The check array below).$country— the billing country code, as WooCommerce stores it (GR, notEL).
The return value is cast to bool and passed to WC()->customer->set_is_vat_exempt(). It is also what is recorded as _gmvat_exempt on the order.
The filter runs whenever the exemption is evaluated — on each checkout refresh, at checkout validation, on the Store API customer updates, and when the order evidence is written — so keep it fast and side-effect free.
Northern Ireland (XI) numbers need no filter: the country-match rule already matches an XI number to a GB billing address with a BT delivery postcode, for carts that need shipping. See How it works.
gmvat_settings (filter) — Full edition
Filters the merged settings array (defaults plus stored values) every time settings are read. Must return an array; anything else is ignored.
apply_filters( 'gmvat_settings', array $settings );
The free edition does not apply this filter.
gmvat_modules (filter) — Full edition
Filters the ordered list of module instances the plugin boots (CoreModule, LicensingModule, VatModule, AdminModule). Entries that are not GatemiVatNumberModuleModuleInterface are dropped.
gmvat_booted (action) — Full edition
Fires once every module has booted, with the plugin's service container.
do_action( 'gmvat_booted', GatemiVatNumberContainerContainer $container );
Licensing filters — Full edition
| Filter | Default | What it tunes |
|---|---|---|
gmvat_license_api_url |
gatemi.com licensing endpoint | The licence API base URL (for staging mirrors) |
gmvat_update_cache_ttl |
12 hours | How long the update payload is cached (min 60 s) |
gmvat_update_retry_ttl |
15 minutes | Retry delay after a failed update check (min 60 s) |
gmvat_sync_cache_ttl |
12 hours | Cache lifetime for licence sync data (min 60 s) |
gmvat_cache_ttl (filter) — Full edition
How long a VIES answer is remembered in the shopper's session, in seconds.
apply_filters( 'gmvat_cache_ttl', int $ttl ); // default HOUR_IN_SECONDS
A remembered answer older than this is asked again. An unavailable answer is remembered for one minute at most, whatever the filter returns, so the tax can come off once VIES is back. A changed number, or an emptied cart, also asks again.
The free edition has no such filter: it keeps a valid or invalid answer for the session, and an unavailable one for one minute at most.
The check array
What the VIES client returns and what is stored in the session:
| Key | Type | Meaning |
|---|---|---|
status |
string | valid, invalid, unavailable or malformed |
number |
string | The cleaned number, prefix included |
name |
string | Name returned by VIES, or '' (VIES's --- placeholder is read as '') |
address |
string | Address returned by VIES, or '' (likewise) |
consultation |
string | VIES requestIdentifier, or '' |
checked_at |
string | UTC, Y-m-d H:i:s |
reason |
string | For unavailable: the transport error, VIES answered {code}., or the first VIES error word (e.g. MS_UNAVAILABLE) |
The VIES verdict is read from the reply's valid key, falling back to isValid.
Order meta
Written with $order->update_meta_data() (HPOS-safe), only when a VAT number was given:
| Key | Value |
|---|---|
_gmvat_number |
Cleaned number |
_gmvat_status |
valid / invalid / unavailable / malformed |
_gmvat_checked_at |
UTC timestamp, Y-m-d H:i:s |
_gmvat_exempt |
yes / no |
_gmvat_name |
name . ' ' . address, trimmed — only when VIES returned a name |
_gmvat_consultation |
Consultation number — only when VIES returned one |
On the Checkout block, WooCommerce additionally stores the field's value as typed under _wc_billing/gatemi-vat/number on the order and the customer.
Reading the evidence:
$order = wc_get_order( $order_id );
$status = $order->get_meta( '_gmvat_status' );
$exempt = 'yes' === $order->get_meta( '_gmvat_exempt' );
Field ids and keys
| What | Value |
|---|---|
| Classic checkout field key (billing group) | gmvat_number |
| Classic field CSS class | gmvat-field (plus form-row-wide) |
| Block checkout field id | gatemi-vat/number (location address, type text) |
| Block field meta key | _wc_billing/gatemi-vat/number |
| Session key | gmvat_check (the check array) |
Block validation WP_Error code |
gmvatf_vat_number (free), gmvat_vat_number (full) |
Options
| Option | Edition | Contents |
|---|---|---|
gmvat_settings |
both | The settings array — see Settings |
gmvat_license |
full | Licence state |
The free edition keeps keys it does not use (own_number, exempt_home, trust_offline) intact when it saves, so a site that moves back to the full edition finds them where it left them. It never reads them.
WooCommerce hooks used
| Hook | Purpose |
|---|---|
woocommerce_checkout_fields (filter) |
Add the classic field |
woocommerce_checkout_update_order_review |
Re-check and set the exemption as the classic checkout refreshes |
woocommerce_checkout_process |
Validate on "Place order"; refuse malformed / invalid numbers |
woocommerce_checkout_create_order |
Write the evidence (classic) |
woocommerce_cart_emptied |
Forget the session check and clear the exemption |
woocommerce_init |
Register the block field |
woocommerce_store_api_cart_update_customer_from_request |
Set the exemption as the block cart address changes |
woocommerce_store_api_checkout_update_customer_from_request |
Set the exemption at block checkout |
woocommerce_store_api_checkout_update_order_from_request |
Write the evidence (block) |
add_meta_boxes |
The "VAT number" box on shop_order and woocommerce_page_wc-orders |
Constants
| Constant | Edition |
|---|---|
GMVATF_VERSION, GMVATF_PLUGIN_FILE, GMVATF_PLUGIN_DIR, GMVATF_PLUGIN_URL |
free |
GMVAT_VERSION |
full — the free edition stands down when it is defined |
External requests
- VIES:
POST https://ec.europa.eu/taxation_customs/vies/rest-api/check-vat-number, JSON body{ "countryCode", "vatNumber" }; full edition addsrequesterMemberStateCodeandrequesterNumber. Timeout from thetimeoutsetting (3–30 s). - gatemi.com: full edition only, and only for licence activation, re-checks and updates once a key is entered.
