Gatemi Order Import Developer Reference

The free edition applies no filters or actions of its own. Everything under Filters and Actions is the full edition's. Options, meta and the export route are shared by both.

Storage

What Name Notes
Settings option gmoi_settings batch (string, "5000"), dry_first (yes/no), allow_update (yes/no). Shared by both editions.
Licence option gmoi_license Full edition. The licence state. Its presence is how the free edition's uninstall knows the full edition was used here.
Update cache gmoi_update_payload (transient) Full edition.
Order meta _gmoi_ref Full edition. The reference from the file. The one identity an order import is keyed on.
Cron gmoi_license_check Full edition. The licence check. Nothing about importing is scheduled.

There are no custom tables, no post types and no files written to disk.

Finding an imported order

$ids = wc_get_orders( array(
	'limit'      => 1,
	'return'     => 'ids',
	'meta_key'   => '_gmoi_ref',
	'meta_value' => 'SHOP-1001',
) );

That is the same lookup the importer uses, and it works with both HPOS and the legacy order tables.

The export route

Both editions answer the same request:

/wp-admin/admin.php?page=…&gmoi_export=coupons&_wpnonce=…
  • Query argument gmoi_export, nonce action gmoi_export_coupons.
  • Capability manage_woocommerce (also required for the import screen).
  • Handled on admin_init, before any output. The response is text/csv; charset=utf-8, file name coupons-YYYY-MM-DD.csv, streamed straight to the browser with a UTF-8 byte-order mark.

A link with an invalid nonce or from a user without the capability is ignored and the normal admin page loads.

Filters — Full edition

gmoi_columns

The column list for one kind of file. It drives header matching, the column table on the screen and the export.

Argument Type
$columns array column_name => label
$kind string orders or coupons

A column you add is recognised (it no longer appears under "not recognised"), is imported as order or coupon meta under its own name (a non-empty cell only; a name starting with _ is refused, because those keys are WooCommerce's own), and, for coupons, exported through gmoi_coupon_cell. Removing a built-in column makes the importer treat it as unknown.

gmoi_coupon_cell

The value of one exported cell for a column the plugin does not know — that is, one added through gmoi_columns.

Argument Type
$value string ''
$column string The column name
$coupon WC_Coupon The coupon being exported

The value is still neutralised against spreadsheet formulas afterwards.

// Export each coupon's usage count in a "times_used" column.
add_filter( 'gmoi_columns', function ( $columns, $kind ) {
	if ( 'coupons' === $kind ) {
		$columns['times_used'] = 'Times used';
	}
	return $columns;
}, 10, 2 );

add_filter( 'gmoi_coupon_cell', function ( $value, $column, $coupon ) {
	return 'times_used' === $column ? (string) $coupon->get_usage_count() : $value;
}, 10, 3 );

gmoi_settings

The merged settings array, after the defaults, on every read.

Argument Type
$settings array batch, dry_first, allow_update
// On a staging site, never let an import change existing records.
add_filter( 'gmoi_settings', function ( $s ) {
	if ( 'staging' === wp_get_environment_type() ) {
		$s['allow_update'] = 'no';
	}
	return $s;
} );

gmoi_modules

The ordered list of modules the plugin boots. For tests and debugging.

Licensing and updates

Filter Default
gmoi_license_api_url gatemi.com's licensing endpoint Point at a staging mirror.
gmoi_update_cache_ttl 12 hours How long the update payload is cached, in seconds (minimum 60).
gmoi_update_retry_ttl 15 minutes How soon to retry after a failed update check.
gmoi_sync_cache_ttl 12 hours How long a licence sync answer is cached.

Actions — Full edition

gmoi_booted

Fires once all modules have booted, with the plugin's service container as its argument. For tests and integrations that need a service:

add_action( 'gmoi_booted', function ( $container ) {
	$importer = $container->get( 'coupon_importer' );
} );

Service ids: settings, coupon_importer, order_importer, coupon_exporter, license.

Running an import from code — Full edition

add_action( 'gmoi_booted', function ( $container ) {
	if ( ! defined( 'WP_CLI' ) ) {
		return;
	}
	$report = $container->get( 'coupon_importer' )->import( '/path/to/coupons.csv', true ); // true = dry run.
	WP_CLI::log( $report->summary() );
	foreach ( $report->problems as $p ) {
		WP_CLI::log( "Line {$p['line']}: {$p['message']}" );
	}
} );

import( string $path, bool $dry_run ) returns an ImportReport with rows, created, updated, skipped, problems (each line and message, capped at 200) and ignored_columns. The order importer has the same signature.

Admin screen

Free edition Full edition
Menu WooCommerce → Coupon Import WooCommerce → Import
Page slug gmcif-coupon-import gmoi-import
Import nonce gmcif_run_import gmoi_run_import
Settings nonce gmcif_save_settings gmoi_save_settings
Posted file field gmcif_file gmoi_file

Only a file PHP received on the current request (is_uploaded_file()) is read; a path typed into a form field is refused.

Uninstall

  • Full edition: removes gmoi_settings, gmoi_license, the update transient and the licence cron event.
  • Free edition: removes gmoi_settings only when gmoi_license does not exist — that is, when the full edition has never been set up on this site.
  • Neither touches a coupon, an order or the _gmoi_ref meta. An imported coupon is an ordinary coupon, and a customer may already have its code.
Shopping Cart
Scroll to Top