Gatemi Birthday Coupons Developer Reference

The free edition applies no filters or actions of its own. Everything under "Filters" and "Actions" is the full edition's. The storage is shared by both editions.

Filters — Full edition

gmbd_settings

apply_filters( 'gmbd_settings', array $settings ) — the merged settings array, after defaults. Return an array; anything else is ignored.

gmbd_due_customers

apply_filters( 'gmbd_due_customers', WP_User[] $users, string $kind ) — the customers one daily run considers, before anything is claimed or minted. $kind is birthday or anniversary. Remove users here to exclude them (for example a "no marketing" role).

gmbd_batch_size

apply_filters( 'gmbd_batch_size', int $size = 2000, string $kind ) — how many users one page of a run reads, per kind. Clamped to 1–20,000. The run pages through every customer, so this bounds the size of one query, not how many customers are reached.

gmbd_coupon

apply_filters( 'gmbd_coupon', WC_Coupon $coupon, int $user_id, string $kind ) — the coupon after every restriction is set and before it is saved. Return anything but a WC_Coupon to cancel: nothing is saved, the claim is released and the customer is tried again on the next run.

gmbd_email

apply_filters( 'gmbd_email', array $message, WP_User $user, string $code ) — $message has to, subject and body (plain text, placeholders already replaced). Return an array missing any of the three keys, or with an empty to, to send nothing — for example because you send your own email. The coupon has already been minted and claimed at that point.

gmbd_modules

apply_filters( 'gmbd_modules', ModuleInterface[] $modules ) — the ordered module list the plugin boots.

gmbd_license_api_url, gmbd_update_cache_ttl

The gatemi.com licensing endpoint (for staging mirrors) and how long the update payload is cached, in seconds.

Actions — Full edition

  • gmbd_booted — do_action( 'gmbd_booted', Container $container ), after every module has booted.

Storage (both editions)

What Where
Settings option gmbd_settings
Licence state (full) option gmbd_license
Update payload (full) transient gmbd_update_payload
Date of birth user meta _gmbd_dob, YYYY-MM-DD
Anniversary override (full) user meta _gmbd_since, YYYY-MM-DD — read if set, otherwise the account's user_registered date
Last coupon sent user meta _gmbd_last, {kind}:{year}:{code}
Year claim option gmbd_c_{year}_{kind}_{user_id}, value 1, not autoloaded

The claim prefix gmbd_c_ puts the year first, so all claims for a year can be found with one LIKE 'gmbd_c_2024_%' query.

Cron hooks

Hook Edition Schedule
gmbdf_daily Free daily, just after midnight store time
gmbd_daily Full daily, just after midnight store time
gmbd_sweep Full weekly — deletes claims more than a year old (the free edition does the same at the end of each gmbdf_daily run)
gmbd_license_check Full twice daily, only with a licence key

Each daily event exists only while coupons are switched on; turning them off removes it on the next page load.

Form field

The checkout and My Account field is named gmbd_dob (type date). On the checkout it is added to the billing group at priority 200.

Privacy

Both editions register a personal-data exporter and eraser under the id gatemi-birthday-coupons, labelled "Birthday coupons".

Coupons

Coupons are created through WC_Coupon with set_email_restrictions(), set_usage_limit( 1 ), set_usage_limit_per_user( 1 ), set_individual_use( true ) and set_date_expires(); the full edition also sets set_minimum_amount() when a minimum is configured. The description is "Birthday coupon." or "Anniversary coupon.", which you can search for under Marketing → Coupons.

Example: exclude wholesale customers and add free shipping

// Full edition only.
add_filter( 'gmbd_due_customers', function ( $users, $kind ) {
	return array_filter( $users, function ( $user ) {
		return ! in_array( 'wholesale_customer', (array) $user->roles, true );
	} );
}, 10, 2 );

add_filter( 'gmbd_coupon', function ( $coupon, $user_id, $kind ) {
	if ( 'birthday' === $kind ) {
		$coupon->set_free_shipping( true );
	}
	return $coupon;
}, 10, 3 );

Next

Shopping Cart
Scroll to Top