Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

Shipping carriers

This page introduces the shipping add-on and the screens it adds to your store. It is for the store owner who wants a customer's postage to come from a real carrier, and who wants to print the label from the same screen as the order.

Carriers are an add-on, not part of KahunaCart itself. Install the kahunacart-shipping plugin alongside the base plugin and your store can quote live rates, buy labels and track parcels. Leave it out and shipping works exactly as Shipping describes it: your own zones, your own methods, your own rates.

Two facts sit underneath everything else in this chapter.

One aggregator, every carrier. The add-on integrates with a carrier aggregator rather than with USPS, UPS and FedEx one at a time. You hold one account and one key, and every carrier behind that account quotes and prints through the same API. Choose Shippo, EasyPost, ShipEngine or, for stores shipping from the UK and Europe, Sendcloud, which brings Royal Mail, Evri, DPD, PostNL, DHL, GLS and many more.

A carrier never blocks checkout. Every way a carrier can fail — down, slow, switched off, refusing the destination — leaves the method shown unavailable with a sentence on it and your nominated fallback method carrying the order. That is core's own guarantee, described in Shipping rates, and the add-on does not find a new way round it.

Before you begin

  • KahunaCart 1.3.0 or later. That is the release where a variant records its length, width and height, and where a driver can list its services; neither can be worked around from outside.
  • An account with Shippo, EasyPost or ShipEngine and its test API key, or a Sendcloud account and the key pair of a Sendcloud API integration.
  • The kahunacart-shipping plugin installed and enabled, and kahunacart.shipping.manage on whoever is going to set it up.
  • The worker running bin/plugin kahunacart work. Labels are bought while you wait, but tracking, the delivered email and the recovery of an unknown purchase all sit on the queue. See CLI.

What it adds

Where What appears
KahunaCart → Shipping carriers A section of its own, with four tabs: the aggregator and its carrier accounts, the box catalogue, the labels this store has bought, and the plugin's settings form.
An order A parcels panel showing what the packer proposes or what was actually shipped, and a Buy label button that names the price before it spends it.
KahunaCart → Shipping The Carrier and Service fields on a zone method stop being free text. Carrier becomes a list with your aggregator in it, and Service becomes the list of services your carriers actually offer.
A product Customs facts on the Shipping tab — a harmonised code, a country of origin and a description for the form — used only when a parcel crosses a border.
A receipt and a customer's account The parcels on an order, with the carrier's name, the tracking number and a link to the carrier's own tracking page.

The screens in this chapter

Page What it covers
Getting started From an empty install to a real price at checkout and a label in your hand.
Carriers and services Carrier accounts, what lives at the aggregator and what lives here, and how a method binds to a service.
Boxes and packing The box catalogue, how the packer decides, dimensional weight, and how to check its work.
Rates at checkout What the customer sees, what happens when a carrier is slow or down, and the fallback method.
Labels Buying, opening, reprinting and voiding, and the six states a label can be in.
Tracking The webhook, the poll behind it, the seven statuses and the delivered email.
Customs International parcels, where each fact comes from, and what a carrier refuses without.
Selling in more than one currency Why a carrier account has its own currency, and what happens to quotes, labels and customs when it is not the cart's.
Settings reference Every config key with its default and what changing it does.
Developers The driver contract, the routes, the MCP tools, the CLI and the events.

The two permissions

Permission What it allows
kahunacart.shipping.manage Setup: the aggregator, the connection check, carrier accounts, boxes, ship-from addresses, the address check and a product's customs facts.
kahunacart.shipping.labels Buying a label, voiding one, quoting an order and recording a parcel.

Buying is a separate permission because every action on that list spends the store's money or gives it back, which is the same reason core separates kahunacart.orders.refund from kahunacart.orders.manage. Somebody who prints labels all day does not also need to be able to repoint the store at a different carrier account.

Reading a label, its file or its tracking history takes kahunacart.orders.view, because that is what somebody answering "where is my parcel" already holds.

Try it

The add-on is running on the KahunaCart demo store. Add something physical to a cart and change the delivery country to watch the price change, open an order in the admin to see its parcels and tracking history, and open a label to see what comes out of the printer.

Important

The carrier on the demo is simulated. Its two carriers do not exist, its prices are invented, and every label it prints says SIMULATION — NOT VALID FOR POSTAGE across the top. It is there so the screens can be walked without an account anywhere. A real store pastes an aggregator key and gets real prices from real carriers.

The same simulation ships inside the add-on, switched off, so you can walk your own store's screens before you open an account. See Settings reference.

Buying a label is refused on the demo, along with every other change, because it is read-only. See Demo store.

What it does not do

  • A carrier's own API. There is no UPS driver and no FedEx driver. A merchant with their own negotiated UPS contract attaches that account to the aggregator, which is what aggregators are for.
  • Rate shopping. You create a method per service you want to offer, exactly as core's contract says. "Show the cheapest of everything the carrier quoted" is a different feature.
  • Conversion between currencies. A carrier account is billed in one currency, set on its driver. A rate quoted in a currency other than the cart's is skipped, never converted. See Selling in more than one currency.
  • Returns, batches, manifests and pickups. None of them is in this release.