Gatemi Carrier Shipping Developer Reference

The free edition applies no filters or actions of its own. Everything under "Filters" and "Actions" belongs to the full edition.

Free edition

What Name
Settings option gmcsf_settings (client_id, client_secret, origin_zip)
Shipping method id gmcsf_usps (class GMCSF_Method)
Access token transient gmcsf_token_{md5 of key and secret}
Quote transient gmcsf_rates_{md5 of the request}, 10 minutes
Settings screen slug gmcsf-settings
Endpoints https://apis.usps.com/oauth2/v3/token, https://apis.usps.com/shipments/v3/options/search

The rate id is WooCommerce's own gmcsf_usps:{instance id}.

Full edition: filters

Filter Arguments What it tunes
gmcs_settings array $settings The defaults-merged settings
gmcs_carriers array $factories (id ⇒ callable) The carrier registry — add a carrier here
gmcs_modules array $modules The booted module list
gmcs_origin_address array $origin (country, state, city, postcode) The ship-from address for every quote
gmcs_boxes array $boxes The boxes the packer may use
gmcs_packing_method string $method per_item, weight_based or box_packing
gmcs_packages PackedBox[] $packages, array $package, string $method The packed parcels, before quoting
gmcs_rate_request RateRequest $request, array $package The carrier-neutral request
gmcs_carrier_request array $payload, string $carrier_id One carrier's API payload, before it is sent
gmcs_quotes Quote[] $quotes, string $carrier_id A carrier's quotes, before markups
gmcs_rates array $rates, string $carrier_id, RateRequest $request The finished WooCommerce rates
gmcs_cache_lifetime int $seconds (default 43200) How long a quote is cached; at least 60
gmcs_http_timeout int $seconds (default 20), string $url Carrier HTTP timeout
gmcs_http_max_retries int $retries (default 1), string $url Retries for a failed request, 0–3

The licence client also uses gmcs_license_api_url and gmcs_update_cache_ttl.

Full edition: actions

  • gmcs_settings_saved — do_action( 'gmcs_settings_saved', array $settings ) after the screen saves. The plugin itself uses it to retire cached quotes and tokens.
  • gmcs_booted — do_action( 'gmcs_booted', Container $container ).

Full edition: storage

What Name
Settings option gmcs_settings (carrier blocks under carriers)
Cache generation counter option gmcs_cache_generation
Quotes transients gmcs_rates_{md5}
OAuth tokens transients gmcs_token_*
Free-edition import marker option gmcs_free_migrated (set once the free edition's USPS settings and zone methods have been brought across)
Licence option gmcs_license, transient gmcs_update_payload, cron gmcs_license_check
Zone method ids gmcs_usps, gmcs_ups, gmcs_fedex, gmcs_australia_post, gmcs_canada_post

Rate ids are {method id}:{instance id}:{service code}, for example gmcs_usps:3:PRIORITY_MAIL, and …:fallback for the fallback price.

Full edition: how the pieces fit

Packer turns a WooCommerce package into PackedBox parcels; RateAssembler builds a carrier-neutral RateRequest, answers from RateCache if it can, and otherwise asks the carrier. A carrier's whole job is RateRequest → Quote[]. The assembler then applies the currency guard, markups, cheapest-only and the fallback, the same way for every carrier.

A carrier implements GatemiCarrierShippingCarrierCarrierInterface: id(), label(), description(), signup_url(), credential_fields(), option_fields(), services(), supports_sandbox(), origin_countries(), quote( RateRequest $request ): array and test_connection(): array. WooCommerce creates zone methods by class name, so each carrier also needs a small shipping-method subclass.

Quote is constructed as new Quote( $carrier_id, $service_code, $label, $cost, $currency, $transit_days = 0, $meta = array() ).

Example: add a handling charge to every UPS rate

add_filter( 'gmcs_rates', function ( $rates, $carrier_id ) {
	if ( 'ups' !== $carrier_id ) {
		return $rates;
	}
	foreach ( $rates as &$rate ) {
		$rate['cost'] += 2.50;
	}
	return $rates;
}, 10, 2 );

For a fixed markup on one service, the Markup column on the carrier's Services table does the same without code.

Example: ship from a warehouse address that is not the store address

add_filter( 'gmcs_origin_address', function ( $origin ) {
	return array(
		'country'  => 'US',
		'state'    => 'NV',
		'city'     => 'Reno',
		'postcode' => '89502',
	);
} );

Next

Shopping Cart
Scroll to Top