How Gatemi Carrier Shipping Works

Two decisions behind the design

  1. Configure once, not once per zone. Credentials, the ship-from address and (in the full edition) packing and services live on one screen, WooCommerce → Carrier Shipping, and every shipping zone uses them. A zone's method only says how rates are shown.
  2. Modern carrier APIs only, with your own account. USPS's REST API with OAuth (apis.usps.com) — not the retired Web Tools XML — and, in the full edition, the UPS REST API with OAuth, FedEx REST, Australia Post's PAC API and Canada Post's web services. Every request goes from your store straight to the carrier with your credentials.

The flow at checkout

Each time WooCommerce calculates shipping for a zone that contains the method:

  1. Nothing to ship, nothing to do. Lines whose product does not need shipping (virtual, downloadable) are left out. A cart of only those gets no carrier rate.
  2. The cart becomes parcels.
    • Free edition: every unit is its own parcel — three mugs are three parcels. Weight is converted to pounds and dimensions to inches from your store units.
    • Full edition: the Packing method decides: one parcel at the combined weight (split at Maximum parcel weight), one parcel per item, or Pack into my boxes. Box packing checks each item's own dimensions strictly against a box, then fits items together by volume and weight. An item that fits no box ships on its own rather than being dropped.
  3. A quote that is already known is reused. See "Caching" below.
  4. The carrier is asked, one request per parcel, for every service it has for that route.
  5. A service only counts if it priced every parcel. If Priority Mail priced two of three parcels, Priority Mail is not offered: the shopper would be shown a price that cannot carry their whole order. The prices of the parcels are added up per service.
  6. The rate is offered.
    • Free edition: the cheapest service, labelled with your Method title and the service name.
    • Full edition: every enabled service (or the cheapest only), each with your Name at checkout and markups applied. Estimated transit days, where the carrier gives them, and a description of the parcels are attached to the rate as meta data.

Never a made-up number

The plugin offers no rate rather than a wrong one:

  • Free edition: no rate unless the store sells in US dollars — USPS prices in dollars, and a converted figure would be a guess.
  • Full edition: a quote in a currency other than your store's is dropped and written to the log, rather than shown as if it were in your currency.
  • No credentials, no ship-from postcode, or a US destination without a ZIP code: no rate.
  • The carrier is unreachable or refuses the request: no rate.
  • A product in the cart has no weight: no live quote, because the carrier's minimum weight would quote less than the parcel really costs.

When a zone has nothing else, WooCommerce says no shipping is available. Full edition: set a Fallback price on the zone's method to offer a fixed charge instead — when the carrier returns no rates, and when the carrier is switched off or its credentials are missing.

Caching

A live quote is the slowest thing on a checkout page, and WooCommerce re-calculates shipping on every cart update and address change.

  • Free edition: a successful quote is kept for 10 minutes, keyed by ship-from ZIP, destination and parcels. A failure is not kept, so the next calculation asks again.
  • Full edition: quotes are kept for 12 hours (filter gmcs_cache_lifetime), keyed by the whole request. Saving the settings retires every cached quote at once, through a generation counter, and forgets every cached access token — a fixed credential or a changed markup shows on the next page load. A real answer with no rates is cached too, but a failed request — a timeout, a server error, a refused token — is not: the empty answer is remembered for the current page load only, so the next calculation asks the carrier again.

Access tokens are cached until shortly before they expire. If a carrier answers "unauthorised", the token is refreshed once and the request retried.

The mailing date (USPS)

USPS prices from a mailing date. The plugin asks for tomorrow's date, so a mid-checkout cutoff time cannot flip the price.

Logs (full edition)

Errors are always written to WooCommerce → Status → Logs under gatemi-carrier-shipping. With Log carrier requests and responses on, every request and response is written too. Credentials are redacted.

Next

Shopping Cart
Scroll to Top