Gatemi Order Approval Developer Reference

Identifiers

Thing Value
Order status gmoa-awaiting (post status wc-gmoa-awaiting), label "Awaiting approval"
Payment method id gmoa_approval
Settings option gmoa_settings (shared by both editions)
Licence option gmoa_license (Full edition)
Update transient gmoa_update_payload (Full edition)
Cron hook gmoa_license_check (Full edition, only while a key is entered)

The plugin creates no tables.

Order meta

Key Written when Contents
_gmoa_decided_at Approve or decline Local time of the decision, Y-m-d H:i:s
_gmoa_decided_by Approve or decline User id of the person who decided
_gmoa_reason Decline with a reason The reason as typed (sanitized)

WooCommerce hooks used

Hook Use
init Registers the post status.
wc_order_statuses Adds "Awaiting approval", placed before Pending payment.
woocommerce_valid_order_statuses_for_payment Removes the status so it is never payable.
woocommerce_payment_gateways Registers the approval method.
woocommerce_available_payment_gateways (priority 20) Leaves only the approval method when a cart needs approving; removes it otherwise.
bulk_actions-edit-shop_order, bulk_actions-woocommerce_page_wc-orders Adds Approve and Decline.
add_meta_boxes Adds the Awaiting approval box to a waiting order.
woocommerce_order_status_gmoa-awaiting Reduces the order's stock with wc_maybe_reduce_stock_levels() as it starts waiting.
woocommerce_cancel_unpaid_order Returns false for an order carrying _gmoa_decided_at, so an approved order is not cancelled by core's unpaid-order sweep.

Filters and actions — Full edition

The free edition applies no filters or actions of its own.

Hook Type Arguments Use
gmoa_settings filter array $settings The merged settings, after defaults.
gmoa_needs_approval filter bool $needs, int[] $product_ids, float $total Whether the cart at the checkout needs approving. $total is the sum of product price × quantity.
gmoa_email filter array $email, WC_Order $order, string $kind The approval (approved) or decline (declined) email as to, subject, body. Return an empty array to send nothing.
gmoa_approved action WC_Order $order After an order is approved and the email handed off.
gmoa_declined action WC_Order $order, string $reason After an order is declined.
gmoa_modules filter array $modules The ordered module list.
gmoa_booted action Container $container After every module has booted.
gmoa_license_api_url filter string $url The gatemi.com licensing endpoint.
gmoa_update_cache_ttl filter int $seconds How long update information is cached.

gmoa_needs_approval runs after the plugin's own decision, so it can both hold more carts and let more through. It is asked while WooCommerce builds the payment method list for the current cart, so the current user is the customer.

Examples

Hold any cart that is being shipped outside your own country:

add_filter( 'gmoa_needs_approval', function ( $needs ) {
	$country = WC()->customer ? WC()->customer->get_shipping_country() : '';
	return $needs || ( $country && WC()->countries->get_base_country() !== $country );
} );

Notify your sales team on Slack when an order is approved:

add_action( 'gmoa_approved', function ( $order ) {
	my_slack_post( sprintf( 'Order %s approved — awaiting payment.', $order->get_order_number() ) );
} );

Send the decline message through your help desk instead of email:

add_filter( 'gmoa_email', function ( $email, $order, $kind ) {
	if ( 'declined' === $kind ) {
		my_helpdesk_ticket( $email['to'], $email['subject'], $email['body'] );
		return array(); // The order is still declined.
	}
	return $email;
}, 10, 3 );

Approving from code

Use WooCommerce's own API with care: setting a waiting order to pending yourself skips the email and the recorded decision. To find waiting orders:

$waiting = wc_get_orders( array(
	'status' => 'gmoa-awaiting',
	'limit'  => 50,
) );

Constants

The full edition defines GMOA_VERSION, GMOA_PLUGIN_FILE, GMOA_PLUGIN_DIR, GMOA_PLUGIN_URL and GMOA_BASENAME. The free edition stands down when GMOA_VERSION is defined.

Shopping Cart
Scroll to Top