Developer Reference — Sales by Country and Tax Reports

Filters — Full edition

The free edition (Gatemi Sales by Country) applies no filters and fires no actions. Everything below is the full edition, Gatemi Tax Reports for WooCommerce. The same list is printed on its settings screen under For developers.

gmtx_report

The finished report, after rounding and sorting, before it is shown or exported. Return an array; anything else is ignored and the original is used.

add_filter( 'gmtx_report', function ( array $report ) {
	// Drop the store's own country from what is shown and exported.
	$report['rows'] = array_values( array_filter(
		$report['rows'],
		fn( $row ) => 'NL' !== $row['country']
	) );
	return $report;
} );

The period totals are not recalculated after this filter — if you remove rows, adjust net, tax and gross yourself if you need them to match.

gmtx_place_of_supply

The country and state one order is reported under.

Argument Type
$place array country (2 letters, upper case), state, fallback ('yes' or 'no')
$order WC_Order The order

The returned array is merged over the original, so you may return only the keys you change. Returning a non-array keeps the original.

// Orders of a "digital" product: always report under billing.
add_filter( 'gmtx_place_of_supply', function ( array $place, $order ) {
	if ( 'yes' === $order->get_meta( '_my_digital_order' ) ) {
		return array(
			'country'  => strtoupper( substr( $order->get_billing_country(), 0, 2 ) ),
			'state'    => strtoupper( $order->get_billing_state() ),
			'fallback' => 'no',
		);
	}
	return $place;
}, 10, 2 );

fallback set to 'yes' is what counts the order in the "no shipping address" note.

gmtx_report_batch

How many orders are read per wc_get_orders() call. Default 100; values below 1 become 1.

gmtx_settings

The merged settings array (see below), after defaults. Return an array.

gmtx_modules

The ordered list of module instances the plugin boots. Items that do not implement the plugin's module interface are dropped.

Licensing and update filters

Filter Default
gmtx_license_api_url gatemi.com licensing endpoint For staging mirrors
gmtx_update_cache_ttl 12 hours How long update information is cached (minimum 60 seconds)
gmtx_update_retry_ttl 15 minutes How long a failed update check waits before retrying (minimum 60 seconds)
gmtx_sync_cache_ttl 12 hours Cache for licence sync between Gatemi plugins (minimum 60 seconds)

The report array

Both editions build the same shape (the free edition always leaves rates empty).

Key Type
from, to string The range, Y-m-d
currency string The store currency code
orders int Orders counted
net, tax, gross, shipping float Period totals, rounded to the store's decimals
rows array One per country (or country–state), sorted by key
rates array Full edition: one per country and rate, sorted by key
no_place int Orders reported under billing because they had no shipping country
other_currency int Orders left out for being in another currency
currencies string[] Those currencies

Each row: key (DE or DE-BY), country, state (empty unless the state breakdown is on), orders, net, tax, gross.

Each rate (full edition): key (country|rate_id), country, rate_id, label, percent, orders, net, tax, gross. The tax is each tax line's product tax plus delivery tax, less the tax refunded under that rate. The net is what the order's product, delivery and fee lines recorded under that rate, less what was refunded on each (or tax × 100 ÷ percent for an order whose lines carry no tax details). Gross is net plus tax.

The settings option

Option name: gmtx_settings, shared by both editions.

Key Type Default Read by
statuses string[] ['processing','completed'] Full edition
place 'shipping' | 'billing' 'shipping' Full edition
states 'yes' | 'no' 'no' Both
by_rate 'yes' | 'no' 'yes' Full edition

The free edition writes only states and keeps the other keys as they were. The full edition's licence state is in a separate option, gmtx_license.

CSV export — Full edition

The report screen has two downloads. Download CSV links to:

wp-admin/admin.php?page=gmtx-tax-reports&gmtx_export=1&from=YYYY-MM-DD&to=YYYY-MM-DD&_wpnonce=…

It needs the manage_woocommerce capability and a valid nonce; without them the request falls through to the normal screen. The file is named tax-FROM-TO.csv and contains the country table:

Column Content
Country Two-letter country code
State State, if the state breakdown is on; otherwise empty
Orders Orders in the row
Net Rounded, no currency symbol or thousands separator
Tax As above
Gross As above
Currency The store currency code, on every row

Download rates CSV, under the By tax rate table, links to the same address with gmtx_export=rates. The file is named tax-rates-FROM-TO.csv and contains the per-rate table:

Column Content
Country Two-letter country code
Rate The rate's label as the order carries it
Percent The rate's percentage as the order carries it
Orders Orders in the row
Net Rounded, no currency symbol or thousands separator
Tax As above
Gross As above
Currency The store currency code, on every row

The column headings are translated with the plugin. The file starts with a UTF-8 byte-order mark so Excel opens accented characters correctly, follows RFC 4180 quoting, and any cell starting with =, +, -, @, a tab or a carriage return is prefixed with ' so a spreadsheet treats it as text.

Screens and capabilities

Free edition Full edition
Menu WooCommerce → Sales by Country WooCommerce → Tax Reports
Screen slug gmtxf-tax-reports gmtx-tax-reports
Capability manage_woocommerce manage_woocommerce
Date range query args from, to (Y-m-d) from, to (Y-m-d)

Constants

The free edition defines GMTXF_VERSION; the full edition GMTX_VERSION. When GMTX_VERSION is defined, the free edition boots nothing.

Data written

None beyond the options above. No tables, no post or order meta, no transients in the free edition, and nothing on the storefront. Both editions declare compatibility with WooCommerce's High-Performance Order Storage and the Cart and Checkout blocks.

Shopping Cart
Scroll to Top