Gatemi Customer Analytics Developer Reference

Both editions build the same snapshot into the same table and apply the same three hooks while doing it (gmca_batch, gmca_customer, gmca_snapshot_built). The query service and the remaining filters are the full edition's.

The query service — Full edition

Segments are only worth something when another plugin can act on them, so the full edition binds a read-only service, segments, in its container. It reads the snapshot table; it never computes anything.

Get it from the gmca_booted action:

add_action( 'gmca_booted', function ( $container ) {
	$segments = $container->get( 'segments' );

	// Every address in "At risk", biggest spenders first (500 at a time).
	$emails = $segments->emails( 'at_risk', 500, 0 );

	// Which segment one address is in ('' when not in the snapshot).
	$segment = $segments->segment_of( 'anna@example.com' );
} );
Method Returns
counts() array — segment key ⇒ number of customers
emails( string $segment, int $limit = 500, int $offset = 0 ) string[] — addresses in the segment, highest spend first
segment_of( string $email ) string — the segment key, or ''
customer( string $email ) array — the customer's whole row, or empty

It answers addresses, not user ids, because a guest has no user id — an integration handed ids would silently lose every guest.

Segment keys: champions, loyal, potential, new, promising, attention, at_risk, hibernating, lost, and other for "Everyone else".

Filters

gmca_batch — both editions

How many orders one page of a rebuild reads. Default 200.

gmca_customer — both editions

One scored customer just before it is stored. Return an array; its keys are merged over the row.

Argument Type
$row array email, user_id, name, country, orders, total, average, first_order, last_order, days_since, r_score, f_score, m_score, segment, built_at
$email string The address
// Keep staff accounts out of every segment.
add_filter( 'gmca_customer', function ( $row, $email ) {
	if ( str_ends_with( $email, '@myshop.example' ) ) {
		$row['segment'] = 'other';
	}
	return $row;
}, 10, 2 );

gmca_settings, gmca_modules, gmca_license_api_url, gmca_update_cache_ttl — Full edition

The merged settings array, the boot module list, the gatemi.com licensing endpoint (for staging mirrors) and how long the update payload is cached.

Actions

gmca_snapshot_built — both editions

Fires after a rebuild, with one argument: segment key ⇒ how many customers landed in it. Use it to start a mailing after fresh segments exist.

add_action( 'gmca_snapshot_built', function ( $landed ) {
	error_log( 'At risk now: ' . ( $landed['at_risk'] ?? 0 ) );
} );

gmca_booted — Full edition

Fires once the plugin has booted, with its service container.

Storage

Table {prefix}gmca_customers

One row per customer, rebuilt wholesale. Shared by both editions; the schema version is in gmca_db_version.

Column
email Lower-cased billing email — unique
user_id, name, country From their orders (newest wins for name and country)
orders, total, average Count, spend after refunds, average order
first_order, last_order, days_since Dates
r_score, f_score, m_score 1–5
segment The segment key
built_at When this snapshot was built

Indexes: email (unique), segment_total (segment, total), user_id.

Options

Option
gmca_settings Settings, shared
gmca_db_version Schema version, shared
gmca_built_at When the last snapshot finished (UTC), shared
gmcaf_schedule_set / gmca_schedule_set The recurrence each edition's cron event was scheduled with
gmca_license Full edition licence state

Cron

Hook
gmcaf_rebuild Free edition, daily
gmca_rebuild Full edition, at the chosen frequency
gmca_license_check Full edition licence check

CSV export — Full edition

admin.php?gmca_export=<segment key or all>&_wpnonce=… (nonce action gmca_save_settings, capability manage_woocommerce) streams customers-<segment>.csv with the columns email, name, country, orders, total, average, first_order, last_order, days_since, r, f, m, segment, sorted by total descending. Every cell that could start a spreadsheet formula is neutralised.

Admin

WooCommerce → Customers: page slug gmcaf-customers (free) or gmca-customers (full). Add &segment=<key> to list one segment.

Shopping Cart
Scroll to Top