Gatemi VAT Number Developer Reference

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, not EL).

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 adds requesterMemberStateCode and requesterNumber. Timeout from the timeout setting (3–30 s).
  • gatemi.com: full edition only, and only for licence activation, re-checks and updates once a key is entered.
Shopping Cart
Scroll to Top