Thomas Richter
I have a confession. Early in my career I pushed a shipping integration to production and a real label got created with a test address. Someone at the warehouse spent 10 minutes trying to figure out why there was a parcel going to "Test Testsson, 123 Fake Street, Berlin." It is funny the first time. Not the fifth.
Testing shipping integrations is tricky because the systems are inherently stateful and connected to real-world logistics. You cannot just write unit tests and call it a day. But you also cannot be creating actual shipments every time you deploy. Here is how I think about testing shipping integrations properly, and how the Uniship sandbox makes it far less painful.
The sandbox environment
Every Uniship account comes with a sandbox API key. It works exactly like production - same endpoints, same request and response formats, same validation rules - but nothing real happens. No labels get dispatched to carriers. No charges hit your account.
You switch to sandbox simply by using your test API key and pointing to the sandbox URL. The requests you make are identical to production. You send shipment creation requests the same way you would in the real environment, with carrier selection, recipient addresses, and parcel dimensions. The responses look identical too - you get back a shipment ID, a tracking number, and a label URL.
The label PDF is real in the sense that it is properly formatted with correct barcodes and the right layout. You can print it and visually verify it looks right. It just will not work if you actually stick it on a box and drop it at a DHL point. The tracking number resolves within the sandbox but follows a simulated delivery lifecycle.
This matters more than people realize. I have worked with teams who skipped sandbox testing and went straight to production with a "we will just void the test labels" approach. That works until you forget to void one and a courier shows up at your warehouse to collect a parcel that does not exist.
Simulating the full tracking lifecycle
This is where sandbox testing gets genuinely powerful. Real shipments take days to deliver. In sandbox you can accelerate the entire timeline.
You trigger simulated tracking events through a single API call, specifying which events you want to occur - picked up, in transit, out for delivery, delivered. Each event fires the corresponding webhook if you have one configured, so you can test your entire event-handling pipeline end to end. No waiting three days to see if your delivered notification actually fires.
This is critical for testing your Tracking API integration. You can verify that your user interface updates correctly, that email notifications trigger, and that your order management system transitions states properly. All within minutes instead of days.
I remember debugging a particularly nasty issue for a client where their system handled most tracking events fine but broke on a specific edge case - a parcel that showed "in transit" after already showing "out for delivery" due to a rerouting. In production, recreating that scenario would have required waiting for a real rerouting event to happen naturally. In sandbox, I triggered the exact event sequence and found the bug in 20 minutes.
Testing webhooks during local development
Webhooks are the backbone of real-time shipping updates. But testing them locally is awkward because your localhost is not reachable from the internet. There are a few approaches I have seen work well.
The simplest option is tunnelling. You expose your local development server using a tunnelling tool that gives you a public URL, then register that URL as your webhook endpoint in the Uniship sandbox dashboard. It is straightforward and effective, though slightly annoying to manage across a team.
The sandbox dashboard also logs every webhook that gets sent. You can replay any webhook event if you missed it because your server was down or you were not ready yet. This is also excellent for debugging because you can see the exact payload that was sent and what your server responded with.
For automated tests, you can skip the network entirely. Grab the webhook payload format from the documentation and inject it directly into your handler function during testing. This is the fastest approach for unit and integration tests and does not depend on any external connectivity.
Making it part of your deployment process
Your shipping integration should be part of your automated test suite, not something you verify manually after each deploy. The sandbox API key goes into your continuous integration secrets, and your shipping client should accept a configurable base URL so you can point it at sandbox without changing any actual code.
Every time someone pushes code or opens a pull request, the test suite runs against the sandbox. Shipments get created, tracking events get simulated, webhooks get verified. All automatically. All without touching production or creating real labels.
I have set this up for several teams now and the peace of mind it provides is enormous. You stop worrying about whether your shipping integration still works after a refactor. The tests will tell you.
What to actually test
Do not just test the happy path. Shipping has a surprising number of edge cases.
Test what happens when the Address API returns a correction or rejects an address entirely. Test rate comparison when no carrier serves a particular destination - the empty response needs to be handled gracefully. Test label creation with missing fields and make sure your interface shows a clear error instead of failing silently.
Test tracking status transitions, especially out-of-order events. As I mentioned, parcels can show "in transit" after "out for delivery" if there is a rerouting. Your system needs to handle that without breaking. Test webhook signature verification to make sure invalid signatures get rejected. And test timeout handling, because carrier APIs are sometimes slow and your integration needs sensible timeouts and retry logic.
The merchants who invest time in thorough testing see dramatically fewer production incidents. One client told me they went from two or three shipping-related bugs per month to zero for an entire quarter after setting up proper sandbox testing.
The bigger picture
Testing is not glamorous work. Nobody gets excited about writing test cases for shipping label generation. But it is the difference between a shipping integration that works and one that works most of the time. That gap - between works and works most of the time - will cost you in customer support tickets, in refunds, and in lost trust.
We built the sandbox to be as close to production as possible because we have seen what happens when teams skip testing. If you are building on top of our Shipment API or Printing API, spend the time to set up proper sandbox testing. Your future self - and your warehouse team - will be grateful.