Karrio began with someone asking me to connect their application to DHL so they could print shipping labels without going through DHL’s website.
One integration. One label. Reasonable enough. I mean, how hard could it be, right? Well, I was about to find out.
Working with that API was extremely frustrating. So I looked at how other carriers did it and found more of the same. Different documentation but the same familiar problem.
I wanted to make that work easier for the next developer, and so I started building an open-source library they could use instead of having to figure out each carrier’s interface for themselves.
Getting a label out of an application and onto a package should be easier. But once the label is on there, somebody has to deliver the thing. Ideally to the right person. At a price the merchant can afford.
Small details.
Retailers shipping within the borders of a country have very different requirements from the merchants who send packages halfway across the globe, even though both might ask you for rates, labels and tracking.
Before choosing an API, I’d work through five decisions about that operation.
It’s best to start with who you’re serving and where their packages need to go. After you understand that, move on to the costs, carrier relationships and delivery services your product needs to support.
By the end, you should also know what happens when one of those deliveries goes wrong.
Let me walk you through that so you see what I mean.
Subscribe to follow what I’m building and learning.
1. Start with the merchant’s operation
Let’s use a hypothetical retailer that ships within one country.
You need to understand where its customers are and which carriers can reach them, along with what those deliveries require.
What the merchant cares about might vary: it could be keeping shipping costs low, getting valuable items there quickly, or making sure someone signs for them at the door.
Those requirements will shape a lot of the decisions you make going forward because a service that works well for one destination or budget may be a poor fit for another.
Now change the scenario. You’re building a platform for several merchants.
Merchant one serves its city. Merchant two ships across the country. Merchant three goes international and needs customs information.
All their needs become your platform’s requirements. You have inherited variety. Congratulations.
Make sure you are clear about which merchants you can serve with the integration you have, and which additional needs you’re committing to support.
Once you figure out which shipments you need to handle, you can start comparing what it will cost to handle them. Without that scope, a low rate tells you very little about whether a carrier is a good fit for the business.
2. Work out what the business can afford
You need to talk about shipping costs early in your work and it’s never too early, because what the merchant can afford to spend per package affects both its margins and the services it can offer.
The operation you’ve just mapped gives you the destinations and delivery requirements to compare those costs against.
Carrier pricing also depends on the relationship behind the shipment, especially the volume of business you bring.
Negotiations for rates might be on the table depending on how many shipments a business is willing to commit to a carrier. The bigger the operation, the easier it becomes to negotiate, although the actual terms need checking with the carrier.
An existing shipping platform may give a smaller merchant access to negotiated rates through the platform’s carrier accounts. That can be a good reason to use it, provided the rates make sense for the shipments that business actually sends.
Before even deciding on any particular connection, I would want to see the services and costs for the usual destinations of our retailer. For a merchant with several possible carriers, the software needs to help it choose a service it can afford that also meets its delivery requirements.
If the rates that make this work come through a platform’s carrier account, that becomes part of your decision too. You need to understand the relationship you’re entering to get those rates, including how much you will depend on that platform after the package leaves.
3. Separate the API choice from the carrier account
At this point, you have two related choices to make:
How your software will connect to the carrier.
Whose account it will use to ship.
For the connection, you can integrate directly with the carriers you work with or use software where someone has already done those integrations. Karrio comes from the second approach: a common interface for requesting rates, generating labels and retrieving tracking information.
Reuse the work.
Its integration documentation describes those workflows.
Using a platform, however, still leaves you with the account decision. You might connect your own carrier account or use accounts supplied through the platform, with its negotiated rates.
I’ve heard about the friction this creates when a merchant needs help but depends on the intermediary that holds the account to deal with the carrier. The merchant wants an answer. Another company has to join the conversation before it can get one.
I’d just advise you to understand the dependency before choosing it, including who can investigate a missing shipment, who contacts the carrier, and who keeps the merchant informed while that happens.
Once you’re clear on the connection and the account, you can look more closely at the services they give you access to. Our retailer still needs a particular kind of delivery, and that means checking what it is actually buying when it generates a label.
4. Understand the service behind the label
Carriers offer different products, with different costs and delivery arrangements. Some use ground transport and some use air, while the names and options vary between carriers. Your application has to preserve the differences that matter to the merchant.
OK, let’s take the example of a merchant that ships valuable items, wants a fast service and requires an adult signature at delivery. Choosing the fastest option does not mean that it includes the signature service it needs, so you have to check both requirements.
FedEx’s signature options, for example, distinguish between direct and adult signatures, which affects who can accept the delivery.
Your product has to let the merchant request the right option, and the integration has to support it for the chosen service. I’d check that before building a workflow around the assumption that every service can do it.
Assumptions are wonderfully convenient during development. Less so when you have to explain them to the merchant.
When you design a common interface, keep those options visible enough for the merchant to choose the service it needs.
So now we have a service that fits the requirement and the budget. Before buying its label, there’s one more detail to check: the address we’re asking the carrier to find.
5. Plan for address errors and delivery problems
If you’ve used a mobile phone keyboard, you know how easy it is to make a typo.
Your thumb slips. The address changes. Your application passes it straight through... no questions asked.
Now somebody may have to resolve the problem after the shipment is underway. I’d prefer to remain asleep at 2 a.m. I suspect you would too.
Work out whether your chosen integration includes address validation, whether it’s a separate service, and what your application will do when it sees a problem.
The result needs to help the merchant or customer correct the information ASAP, while keeping clear what the check can actually establish.
And sometimes an address can be valid while a particular carrier doesn’t serve it, so our retailer needs to check both the destination information and the service available for that shipment.
Once the package leaves, the merchant and recipient need visibility into its journey, especially when something requires attention.
If it goes on hold, the merchant needs to find out why and understand what it can do next.
That takes us back to the account relationship we talked about earlier. An update that tells you a package is stuck gives you a starting point, but you also need to know who can act on it.
The tracking info and the route to getting help both belong in the product you’re building.
By now, you have enough to describe the shipment from the merchant’s request through to a delivery or a problem that needs resolving. I would use that to test the integration before going ahead and committing to it.
Walk through one shipment
Sit down with the person responsible for shipping and choose a shipment their business actually needs to send. Start with its destination and delivery requirements, then compare the available services and rates using the account you expect to ship through.
Follow that choice through the entire workflow.
Check the address, the label, how the required delivery options get selected, and what tracking information comes back.
Then make the hypothetical shipment a nightmare shipment.
Put an error in the address. Add a signature requirement. Have the package go on hold. Follow the steps the merchant would take to resolve every single one of those situations.
On paper, please. The carrier has enough going on.
Prepare for the worst but pray for the best.
If you’re building a platform, repeat the exercise for merchants with different needs. The local seller and the international seller should both be able to complete the workflow you’re promising them.
Write down the steps, including who handles the parts the software can’t, and use that to compare your integration options. Take unanswered questions back to the provider before committing. If a package goes missing, you and the merchant should know who makes the next call.
Now go build something amazing.
Preferably something that lets you sleep.
—Dan
Thanks for reading, . I hope this gave you something to think about. If you’d like more, subscribe, I’d be glad to have you back.





