Getting started with carriers

This page takes you from an empty install to a real carrier price at checkout and a label you can print. It assumes KahunaCart is already selling; if it is not, start with Getting started and come back.

Two of the steps happen on Shippo's website rather than in your admin, and nothing changes about how your store prices shipping until you turn carrier rates on near the end.

Before you begin

• KahunaCart 1.3.0 or later, on a store that can already take an order.
• A Shippo account for this walkthrough, or a ShipEngine, EasyPost or Sendcloud account if you choose that provider.
• kahunacart.shipping.manage and kahunacart.settings on your account. Buying the label at the end also needs kahunacart.shipping.labels.

Install the add-on

1. 1

   Install the plugin.

   BASHCopy

   bin/gpm install kahunacart-shipping
   

2. 2

   Look at what the migrations will do, then run them.

   BASHCopy

   bin/plugin kahunacart migrate --status
   bin/plugin kahunacart migrate
   

   shipping_0001_core and shipping_0002_labels create seven tables. Running migrate a second time applies nothing.

3. 3

   Check the worker is draining the queue.

   BASHCopy

   bin/plugin kahunacart work --once
   

   On a live store this is a cron entry running every minute. Labels are still bought and voided without it, because both happen while you wait, but nothing is tracked and no delivered email goes out.

Shipping carriers now appears in the KahunaCart admin sidebar.

This walkthrough uses Shippo. For ShipEngine, follow the eight setup steps, then continue below with boxes and zone methods. Use the ShipEngine webhook instructions when you reach tracking. For Sendcloud, follow Set up Sendcloud, then continue below with boxes and zone methods; its webhook is registered from the carriers screen, as described in Sendcloud webhooks.

Paste your Shippo key

1. In Shippo, open Settings → API and copy the key that begins shippo_test_. There is a live key beside it beginning shippo_live_. Leave that one alone for now.
2. In the admin sidebar, click KahunaCart, then Shipping carriers, then the Settings tab.
3. Open the Shippo tab and paste the key into Test token.
4. Click Save in the admin header.

Test mode quotes real prices and prints real-looking labels that nobody can post and nobody is charged for, which is what you want while you are setting this up.

Check the connection

1. Open KahunaCart → Shipping carriers.
2. Click Check connection.

The card reports which Shippo account it reached and how many carrier accounts that account holds. A failure shows Shippo's own words rather than ours, because "Invalid token." tells you what to do and "connection failed" does not.

Switch your carriers on at Shippo

This is the step people miss. Carrier accounts are created in Shippo's own console, on its Carriers page, and there is no way to do it from your admin.

• USPS usually comes with the account and is already on.
• UPS needs its terms accepted in Shippo's web app. There is no API for it, and until it is done UPS quotes nothing and says nothing about why.

Then come back to KahunaCart → Shipping carriers and click Refresh carriers. That is what pulls the carrier accounts and their service codes over to your store.

Your own on and off switches survive a refresh. Turning FedEx off here keeps it out of every quote whatever its state is at Shippo.

Add a ship-from address

A carrier will not quote, and will certainly not print a label, without knowing where the parcel starts.

1. Open KahunaCart → Shipping carriers.
2. Under Ships from, click Add an address.
3. Enter a name, a street, a town, a region, a postcode and a country.
4. Click Save.

Core's own invoice.store_address is a free-text block meant for the bottom of an invoice, which no carrier API can take. This is a structured address kept separately.

Fill in some boxes

1. Open KahunaCart → Shipping carriers and the Boxes tab.
2. Click Add a box.
3. Enter a code, a name, the outside measurements in whole millimetres, and a maximum weight in whole grams.
4. Click Save, and repeat for each box you actually post things in.

A store with no boxes still quotes, on one built-in box, with every parcel marked as an estimate. It is better than not quoting and worse than the truth. See Boxes and packing.

Sizes on your products matter just as much. A variant records length_mm, width_mm and height_mm beside its weight, under Size in the variant editor, and a line with none of those is something the packer has to guess about.

Bind a method to a carrier service

1. In the admin sidebar, click KahunaCart, then Shipping.
2. Click Edit on a zone, and open one of its methods.
3. Set Carrier to your aggregator.
4. Set Service to one of the services in the list. The list comes from the carriers you switched on, as of the last refresh.
5. Click Save.

The method is now priced by the carrier instead of by the figure you typed. Create one method per service you want to offer.

Turn carrier rates on

Two settings, both on KahunaCart's own Shipping screen and both core's rather than this add-on's.

1. Set Live carrier rates to on (shipping.carrier_rates.enabled). Until this is on, a method bound to a carrier is shown unavailable and no carrier is ever asked anything.
2. Set Fallback method to an ordinary flat-rate method you already trust (shipping.carrier_rates.fallback_method_id).

The fallback carries the checkout whenever a carrier is down, slow or switched off. Nominate one yourself: "the cheapest remaining method" would ship pallets by letter post the day a courier's API goes down.

Put something physical in a cart and go to checkout. The method now shows a price that came from the carrier.

Buy your first label

1. Open KahunaCart → Orders and an order with something left to ship.
2. In the parcels panel, click Buy label.
3. Read the parcels the packer made, pick a service, and check the address panel.
4. Click the confirm button. It names the price: Buy this label for $9.41, not Confirm.

The label is bought, the file is downloaded and kept on your server, the parcel is recorded on the order, and the shipped email goes out with a working tracking link on it.

Set up inbound tracking

Optional. Without it, parcels still move — the poll asks about every parcel in the air every six hours — they just move up to six hours late.

1. Make yourself a long random string. openssl rand -hex 24 is one way.
2. Put it into Settings → Shippo → Webhook secret and save.
3. Build your store's tracking address out of it: https://your-store.example/api/v1/kahunacart/shipping/public/webhook/shippo/<your secret>
4. Register that address in Shippo, on its Settings → Webhooks page, for the track_updated event.

The address has to be https and under 200 characters, both of which are Shippo's rules. See Tracking.

When you are ready for real money

1. Paste the live key into Settings → Shippo → Live token.
2. Set Mode to Live.
3. Click Check connection again.

Nothing else changes.

Related

• Carriers and services
• Boxes and packing
• Labels
• Settings reference
• Shipping - the zones and methods this binds onto