Tracking
Once an order is sent, the provider makes it, packs it and posts it. Each parcel it sends comes back onto the KahunaCart order as a shipment, with the carrier, the tracking number and a link, and KahunaCart's own shipped email goes to the customer. You don't type anything in.
Before you begin
- The webhook registered for each provider, which needs the store's public
httpsaddress. Gelato's is added by hand. - The job worker running. Every delivery and every poll is a job.
How the store hears about it
Two ways, and both end in the same place.
Webhooks. The provider tells the store when something happens. Register them with Register webhook on the provider's card (Gelato's are added by hand; see Gelato). They need the store's public https address.
A delivery is treated as a doorbell, never as the truth. The store checks it (the size, the secret in the address and, where the provider signs, the signature over the exact bytes), writes it to the delivery log, and queues a job to read the order back from the provider. Only what the provider says on that read is written to the order. A burst of deliveries about one order is one read.
| Check | Answer when it fails |
|---|---|
| Too large | 413 |
| Wrong secret in the address | 404 |
| Bad signature (Printful, and Printify once it has signed) | 401 |
The poll. Every Check orders every hours (tracking.poll_hours, 4 by default) the store reads back every provider order that is still open and was sent less than Stop checking after days ago (tracking.poll_until_days, 60). It stops at delivered, cancelled or returned, and at the day limit. This is what keeps tracking right when a webhook never arrives: Printful gives up retrying after about a day, Gelato after three tries.
Check again on the order reads it back on the spot.
Parcels
- Each parcel is recorded once, however many times the provider mentions it.
- A partly shipped order is Partly shipped until the last parcel leaves. The customer gets a shipped email per parcel.
- The carrier is matched to KahunaCart's list of carriers. One it does not know is recorded as Other, with the provider's tracking link, so the customer's link still works.
- Delivered stamps the delivery time on the shipment.
- A replacement parcel (the provider sending the same items again) cannot be a second KahunaCart shipment, because core refuses more units than were ordered. It is kept by the add-on and written into the order's history with its carrier, number and link, and the customer gets no shipped email for it. Send them the link yourself if they ask.
Each provider has one wrinkle:
- Printful names the items in each parcel. Nothing more to it.
- Gelato hands out a tracking code before a parcel leaves. A Gelato parcel becomes a shipment only once its items have actually shipped.
- Printify names a parcel's items by SKU. When the store cannot be sure which line a parcel holds (two lines with one SKU, say), it records nothing rather than guess, and you get a notification asking you to record it by hand.
What the customer sees
While printed items are being made, the receipt, the order emails and the customer's order list in their account show a made for you note: which items are still being made and roughly how many days printing takes. It never names the provider, the cost or the provider's own status words. Once every item has left, KahunaCart's ordinary parcels list takes over, with the tracking links.
The delivery log
Every webhook delivery is logged, and the provider's card shows the last few under Webhook. Rows older than thirty days are swept daily.