Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

Rates at checkout

This page covers what happens between a customer entering an address and a price appearing beside a shipping method, and what happens on the days the courier does not answer.

Before you begin

  • A method bound to a carrier service. See Carriers and services.
  • shipping.carrier_rates.enabled on, and shipping.carrier_rates.fallback_method_id nominated. Both are on KahunaCart's own Shipping screen and both are core's, not this add-on's.

What happens at checkout

  1. KahunaCart works out which zone the address is in and which methods that zone holds.
  2. For a method bound to a carrier, the add-on is asked whether it has anything to say at all. A store with no ship-from address, no carrier switched on, or an order with no country, declines here and no call is made.
  3. The packer turns the package into parcels. See Boxes and packing.
  4. The add-on asks the aggregator for a price for that service, naming only the carrier accounts you have switched on.
  5. KahunaCart clamps the answer with the method's own minimum and maximum, caches it, and offers it.

The customer sees the method with a price on it. Nothing about the box, the parcel count or the aggregator reaches them.

Turn carrier rates on

  1. In the admin sidebar, click KahunaCart, then Shipping.
  2. Set Live carrier rates to on.
  3. Set Fallback method to an ordinary flat-rate method you already trust.
  4. Click Save.

Carrier-priced methods now quote. Until Live carrier rates is on, every method bound to a carrier is shown unavailable and no courier is ever asked anything.

Important

Nominate the fallback yourself. It defaults to nothing, and "the cheapest remaining method" would ship pallets by letter post the day a courier's API goes down.

When a carrier does not answer

A carrier never blocks checkout. Every failure leads to the same outcome: the method is present, disabled, carrying a sentence, and the fallback method carries the order.

What happened What the customer sees Reason code
The courier quoted the service The method, at the quoted price, clamped -
The courier will not carry this parcel by this service The method, disabled carrier_excluded
The courier quoted nothing about it The method, disabled calculator_declined
The courier timed out or errored The method, disabled carrier_unavailable
The store has no ship-from address or no carrier switched on The method, disabled carrier_unavailable
A line is in a class this carrier will not take The method, disabled, naming the product item_excluded
Live carrier rates is off The method, disabled carrier_unavailable
The add-on is switched off or uninstalled The method, disabled carrier_unavailable

The full table, with what a theme prints for each reason, is in Shipping rates.

Note

A courier's own refusal sentence — "this service will not take a parcel over 900 mm on its longest side" — is carried on the offer but is not what a stock theme prints. The theme prints KahunaCart's generic sentence for carrier_excluded. A theme can print the specific one by preferring offer.reason_params.detail_key over offer.reason_key. The admin already prints the specific one, so the same refusal can read two ways depending on which screen you are on.

The timeout

shipping.carrier_rates.timeout is a per-driver, wall-clock budget in seconds, and it defaults to 5. A courier that comes back late has its answer discarded and the method goes unavailable.

The add-on's own timeout setting is a different number for different calls: it covers buying a label and asking about tracking, neither of which happens during a checkout. Rates run inside core's budget only.

The cache

A quote is cached on a hash of the destination, the parcel contents, their weight, their declared value and the currency, for shipping.carrier_rates.cache_ttl seconds — nine hundred by default.

A courier that answered with nothing is cached as nothing, so a courier refusing a destination is not asked again on every keystroke.

To clear it after your account manager changes a rate card, use POST /kahunacart/shipping/carriers/cache/clear, which is core's route. Saving a method's rates clears the set as well.

Postage in and postage out

The customer's postage and your label cost are two different numbers.

The customer pays what the method quoted and clamped. You pay what the label cost when you bought it. The add-on records both and never reconciles them automatically: it reports the difference and it never adjusts an order. A store that under-quoted a parcel finds out on the Labels tab rather than by having a customer's total change after they paid.

Check it is working

  1. Put something physical in a cart and go to checkout.
  2. Enter an address in a zone that holds a carrier-bound method.
  3. The method should show a price that is not the figure you typed into it.

Then break it on purpose, because the failure path is the one worth seeing before a customer does: switch the carrier off on the Shipping carriers screen and reload the checkout. The method should go unavailable with a sentence, and your fallback should be carrying the order.