Shipping APIs explained: rates, labels, tracking, and the build versus buy call

Somewhere in every commerce, marketplace or logistics codebase is the moment software has to talk to a shipping carrier: quote the customer a delivery price, buy a label when the order is packed, tell the customer where the box is. A shipping API is the interface that makes those moments programmable, and the choice of which one, and how to integrate it, quietly shapes checkout conversion, fulfillment cost per order, and how much engineering time logistics eats forever after.

This guide is written for the two people who usually share the decision: the engineer who has to integrate the thing and the operator who has to pay for it. It covers what the API actually does call by call, the structural difference between aggregators and direct carrier integrations, the request flows worth understanding before you design your order pipeline, what the pricing models cost once volume is real, and a playbook that gets a team from sandbox to production without the classic mistakes.

It pairs with two neighbors on this blog: our guide to implementing a supply chain system for the warehouse side of the same pipeline, and our breakdown of what inventory management software is for the stock ledger a shipping integration reads from. This one stays on the parcel: getting a box from your dock to a doorstep, through an API.

What a shipping API actually does, call by call

Strip the marketing and a shipping API is five families of calls. Rating: given a parcel (dimensions, weight, origin, destination, service level), return prices and delivery estimates. Label purchase: commit to a shipment and get back a label file, a tracking number, and a charge against your account. Tracking: query or subscribe to the status of a package in transit. Pickup and manifest: schedule a carrier collection and close out the day's shipments. Address validation: check and normalize a destination before you pay to ship to a typo.

Each family has a different place in your system. Rating lives inside checkout or cart, where a slow response is abandoned revenue, so it is the call you cache, parallelize across carriers, and wrap in timeouts with a fallback flat rate. Label purchase lives in fulfillment, where correctness beats speed: it moves money, so it needs idempotency keys, retry discipline, and a void flow for the labels you buy and never use. Tracking is a firehose you consume, not a question you ask: mature providers push status events to your webhook endpoint, and polling is the fallback, not the design.

The less glamorous calls earn their keep at the edges. Address validation runs before rating in a well-ordered pipeline, because carriers surcharge or return undeliverable parcels for address defects, and a correction at checkout costs nothing while a correction in transit costs a support ticket and days. Customs document generation, commercial invoices and harmonized codes for international parcels, is the family teams forget until the first cross-border order, and it is the single strongest argument for using a provider that handles it rather than reading carrier customs specifications yourself.

What a shipping API does not do also matters. It does not decide which carrier or service a given order should use; that logic, cheapest-that-meets-the-promise, or fastest-under-a-cost-cap, is yours, and it is where most of the money is won or lost. It does not manage your inventory or your warehouse; it starts where a packed parcel ends. And it does not negotiate your carrier contract, although some providers resell discounted rates, which becomes a central plot point in the pricing section below.

The vocabulary shipping API documentation assumes

Rate shopping

Requesting quotes from multiple carriers or service levels for one parcel and picking by price, speed or reliability. The core loop most teams integrate a shipping API to run.

Label (and void)

The purchased shipping document carrying the barcode and tracking number. Buying one charges your account; voiding an unused one within the carrier window recovers the cost.

Manifest (end of day)

The closing document that tells a carrier which labels will be handed over in a pickup. Some carriers require it; skipping it can delay scans and muddy tracking.

Webhook tracking

The push model for status updates: the provider posts events (picked up, in transit, out for delivery, delivered, exception) to your endpoint instead of you polling.

Dimensional weight

Billing weight computed from parcel volume rather than scale weight. The reason accurate dimensions in rating calls are a money issue, not a data hygiene issue.

Harmonized code (HS code)

The international customs classification for goods. Required on cross-border commercial invoices, and the field most often wrong in first international integrations.

Aggregators versus direct carrier APIs: the real trade

There are two structural ways to get carrier services into your code. Direct: integrate each carrier's own API, one project per carrier, each with its own authentication scheme, data model, sandbox quirks, and versioning calendar. Aggregated: integrate one provider, an EasyPost, Shippo, ShipEngine, Karrio or a regional equivalent, that has already done the carrier integrations and exposes them behind one normalized interface, for a per-label fee or a subscription.

The aggregator case is mostly about surface area. One data model for rating, labels and tracking across every carrier the provider supports means adding a carrier is configuration, not a project. The provider absorbs carrier API changes, outage weirdness, and the long tail of edge cases that direct integrators discover one incident at a time. For teams shipping across borders, the aggregator's customs handling and multi-country carrier catalog is often worth the fee by itself. The costs are the fee per label, a dependency in the middle of your fulfillment path, and normalization loss: carrier-specific capabilities can lag behind or hide beneath the common interface.

The direct case is about concentration and control. If ninety percent of your volume rides one carrier under a negotiated contract, a single direct integration removes the per-label fee on your biggest lane, exposes every carrier-specific feature the aggregator abstracts away, and takes one third party out of your critical path. The costs are the integration project itself, permanent ownership of carrier API changes, and the fact that the second and third carriers each cost the same again. Teams underestimate the maintenance line most: carrier APIs deprecate versions, change certification requirements, and behave differently under peak load, and that work never ends.

The pattern that actually serves most scaled teams is hybrid: an aggregator for breadth, plus a direct integration on the one or two carriers that carry concentrated contract volume. That gets contract rates and full features where the money is, and configuration-level access to everyone else for rate shopping, coverage gaps, and carrier diversification when a network melts down in peak season. The architecture section below shows where the seam between the two belongs so your order pipeline never has to care which path a shipment took.

Aggregator, direct, or hybrid: what each choice actually buys

	Aggregator only	Direct only	Hybrid
Engineering to first labelOne normalized API versus per-carrier projects	One integration, days to weeks	One project per carrier, weeks each	Aggregator first, direct added later
Adding a carrier	Configuration and credentials	A new integration project	Config for breadth, project for volume lanes
Per-label economics	Provider fee on every label	No middleman fee, contract rates	Fee only on the long tail
Maintenance burden	Provider absorbs carrier changes	You own every carrier's changes	You own only your volume carriers
Carrier-specific features	Normalized, sometimes lagging	Everything the carrier exposes	Full features where they matter
Failure isolation	Provider outage stalls all carriers	One carrier outage stays contained	Volume lanes independent of provider

The request flows worth understanding before you design

The rating flow sets your checkout's speed limit. The naive design calls the API live for every cart view; the workable design treats live rating as the last resort. Cache quotes keyed on origin zone, destination zone, weight band and service level, with a short lifetime; precompute a rate table for your common parcel profiles and refresh it on a schedule; and keep a flat-rate fallback that quotes something sane when the provider is slow or down. A checkout that blocks on a third-party rating call with no timeout is the single most common shipping integration defect, and it is a conversion bug, not a logistics bug.

The label flow is a payment flow wearing a logistics costume, and it deserves payment-flow engineering. Every purchase call carries an idempotency key so a retry after a network blip cannot buy two labels for one order. Every purchased label lands in your own shipment table with its cost, tracking number and raw provider response before anything else proceeds. A reconciliation job compares what the provider billed against what your table says you bought, because rebills, adjustments and dimensional-weight corrections arrive days later. And a void job releases labels for orders that got canceled after packing, inside the carrier's refund window.

The tracking flow is an event pipeline. At small volume you can poll; at real volume you receive webhooks, and the engineering moves to the receiving side: verify the provider's signature so a forged request cannot mark orders delivered, make handlers idempotent because providers redeliver, tolerate out-of-order events because carrier scans are messy, and map the provider's dozens of raw statuses onto the six or so your customers and support team actually act on. The events update your shipment table first; notifications, customer emails and analytics all read from your table, never from the provider directly.

The address and customs flows run before money moves. Validation at checkout catches the undeliverable address while the customer can still fix it; the same call after payment only generates support work. International parcels add the customs document flow: item-level contents with values and harmonized codes, generated with the label, because a parcel that clears your dock without paperwork stops at the border, and border delays are the tracking exceptions customers escalate hardest.

One order, through the API: the canonical sequence

1. 1

   Validate the address at checkoutCheckout

   Normalize and verify the destination before quoting. Surcharges and returned parcels start as address defects that were free to fix at this step.

2. 2

   Rate from cache, fall back to liveCheckout

   Serve cached or precomputed quotes for common profiles; go live only on misses, behind a timeout, with a flat-rate fallback so checkout never blocks.

3. 3

   Buy the label with an idempotency keyFulfillment

   At pack time, purchase the chosen service. The key makes retries safe; the response (cost, tracking number, label file) is written to your shipment table before printing.

4. 4

   Manifest and hand overFulfillment

   Close the day's labels into the carrier manifest and schedule or confirm pickup. First physical scan should follow within hours; alert when it does not.

5. 5

   Consume tracking webhooksIn transit

   Verify signatures, deduplicate, map raw statuses to your internal set, update the shipment table, and let notifications read from your table.

6. 6

   Reconcile and void weeklyFinance

   Compare provider billing against your table, chase dimensional-weight adjustments, and void unused labels inside the refund window.

Pricing models, and where the money actually goes

Every shipping API bill has up to three layers, and conflating them is how teams mis-compare providers. Layer one is postage: what the carrier charges for the movement, by far the largest number. Layer two is the API provider's take: a per-label fee (commonly a few cents, often with a free monthly tier), a subscription, or a percentage on some platforms. Layer three is the discount program: many aggregators resell carrier rates below published retail, funded by their pooled volume, which means the provider can simultaneously charge you a fee and save you money overall.

That third layer reorders the comparison for small and mid-volume shippers. A provider with a slightly higher per-label fee but deeper resold discounts on your actual lane mix frequently wins on total cost, which is why the only honest evaluation is to price your real last month of shipments, your parcels, your zones, your service levels, across candidates, rather than reading fee tables. Teams with negotiated carrier contracts flip the logic: resold discounts are irrelevant, the per-label fee is pure cost on top of contract rates, and the question becomes whether normalization and maintenance relief justify it.

At volume, the per-label fee stops being a rounding error and becomes a line item someone notices. A few cents on tens of labels a day is lunch money; the same few cents on a few hundred thousand labels a year is an engineer's salary, and that arithmetic is exactly the build versus buy trigger the final section works through. Watch the secondary meters too: some providers meter rating calls or tracking lookups separately from labels, and a chatty checkout that rates every cart view can turn a cheap label contract into an expensive rating bill.

The costs nobody puts on the pricing page are operational. Dimensional-weight adjustments arrive after delivery when the carrier re-measures your parcel and rebills the difference, and sloppy dimension data at rating time turns into a steady leak. Address-correction surcharges, residential-delivery surcharges and peak-season surcharges all flow through to you regardless of provider. A provider whose API makes accurate dimensions, validated addresses and correct service selection easy is cutting your surcharge bill in ways a fee table never shows.

The integration playbook: sandbox to production without the classic mistakes

The order of operations matters more than the effort. Week one belongs in the sandbox with test credentials: rate a handful of real parcel profiles, buy and void test labels, and stand up the webhook endpoint with signature verification before any production traffic exists. The goal of week one is not features; it is confirming the provider actually behaves as documented on your lanes, because the gap between shipping API documentation and shipping API behavior is where integration schedules go to die.

Go to production narrow: one carrier, one service level, a slice of real orders. Narrow production traffic surfaces the problems sandbox never shows, real address chaos, real webhook timing, real label printer behavior, while the blast radius stays small. Only after the narrow slice runs clean for a couple of weeks do you add service levels, then carriers, then the rate-shopping logic that picks between them. Teams that integrate breadth-first spend their first peak season debugging six carriers simultaneously.

Build your own shipment table from day one, even though the provider offers a dashboard. Your table, order ID, chosen service, quoted cost, billed cost, tracking number, current status, raw event log, is what your support tools, finance reconciliation and analytics read. Treating the provider as the system of record couples every internal question to their API limits and their retention policy, and makes the eventual provider migration, which happens more often than teams plan for, a data archaeology project instead of a cutover.

Instrument the seams. Alert on rating latency and fallback activation, because that is checkout revenue. Alert on labels bought but never scanned, because that is a parcel sitting on your dock. Alert on webhook silence, because a quiet tracking pipeline usually means your endpoint is rejecting deliveries, not that every package stopped moving. And run the void-and-reconcile job weekly from the first month, because unclaimed label refunds and unnoticed rebills are small numbers that compound quietly.

Shipping integration habits: what holds up and what falls over

Do this

• Idempotency keys on every label purchaseA retry after a timeout must not buy a second label. This is payment-flow discipline applied to postage, and it costs one header.
• Timeouts and a flat-rate fallback on ratingCheckout never blocks on a third party. A slightly imperfect quote beats an abandoned cart every time the provider has a slow day.
• Signature checks and dedupe on webhooksProviders redeliver events and attackers can find endpoints. Verified, idempotent handlers make both facts boring.
• Your own shipment table as source of truthSupport, finance and analytics read your data. The provider dashboard is a debugging tool, not your system of record.

Not this

• Live-rating every cart viewMetered rating calls and third-party latency inside checkout. Cache by zone and weight band; go live only on misses.
• Guessing parcel dimensionsDimensional-weight rebills arrive weeks later as a steady leak. Measure your real packaging profiles once and encode them.
• Skipping the void-and-reconcile jobCanceled orders with purchased labels and silent carrier rebills are free money lost monthly until someone builds the job.
• Launching international without customs dataMissing harmonized codes and invoice values stop parcels at borders. The first cross-border order is the wrong time to discover this.

A reference architecture that survives provider changes

The load-bearing decision in a shipping integration is one interface: put a thin shipping service of your own between your order pipeline and whichever providers you use. Your fulfillment code calls your service with your domain language, quote this order, ship this order, where is this order, and adapters behind it translate to the aggregator or a direct carrier API. It is a small amount of structure, typically one service and one adapter per provider, and it is the difference between a provider migration being a new adapter versus a rewrite of every touchpoint.

Inside that service live the policies that are actually yours: the carrier selection rules that pick cheapest-meeting-the-promise, the caching and fallback behavior for rating, the idempotency and reconciliation machinery for purchases, and the status mapping that turns dozens of raw carrier scan codes into the handful of states your customers see. None of that belongs scattered through checkout and warehouse code, and none of it belongs delegated to the provider, because it encodes your margins and your delivery promise.

The hybrid pattern from earlier drops into this architecture cleanly: the aggregator adapter and the direct carrier adapter sit side by side behind the same interface, and the selection policy routes each shipment by lane and volume without the order pipeline knowing the difference. The same seam is where resilience lives: when a provider degrades, the service can fail over to another adapter, or degrade gracefully to a default service level, while checkout keeps quoting from cache.

Right-size the ambition to your stage. A startup shipping fifty orders a day needs the interface and one aggregator adapter, a few days of work, not a routing engine. The routing policies, the second adapter and the failover machinery earn their complexity only when volume, contract rates or a second warehouse arrive. The architecture is not about building everything now; it is about placing one seam now so that everything later is an addition instead of a rewrite.

The shipping service seam: what belongs inside it

• One internal interface in your domain languageQuote, ship, track, void. Fulfillment code never imports a provider SDK directly, so providers stay swappable.
• Provider adapters, one per integrationAggregator and any direct carriers behind the same interface. Adding or replacing a provider touches one adapter, nothing else.
• Carrier selection policyCheapest-meeting-the-promise, cost caps, lane routing between aggregator and direct paths. This encodes your margin; it is never the provider's job.
• Rating cache and fallback rulesZone-and-weight-band cache, timeout budget, flat-rate fallback. Checkout latency policy lives here, once, not per call site.
• Shipment table and event logEvery quote honored, label bought, event received. The internal source of truth that support, finance and analytics read.
• Reconciliation and void jobsBilled-versus-booked comparison, dimensional adjustment chasing, refund-window voids. The unglamorous machinery that stops silent leaks.

Build versus buy: the honest arithmetic

Frame the question precisely, because "build" hides two different projects. Building direct carrier integrations means replacing the aggregator's middleman role on specific carriers: real but bounded work per carrier, with permanent maintenance. Building a full internal shipping platform, normalized multi-carrier interface, rating engine, tracking pipeline, across many carriers means becoming an aggregator with one customer, and almost no operating company should do it. Most "should we build" conversations are really about the first project on one or two carriers.

The arithmetic that decides it has three inputs. Volume: the aggregator's per-label fee times your annual labels is the budget a direct integration must beat. Concentration: that budget only converts to savings on carriers you can actually take direct, so eighty percent of volume on one carrier makes a strong case and an even spread across six makes none. Engineering cost: a direct carrier integration done properly, certification, edge cases, monitoring, is weeks of work up front and a permanent claim on maintenance attention, and that claim is the number teams undercount.

Worked honestly: a shipper doing 300,000 labels a year at a five-cent fee is paying 15,000 dollars annually for aggregation. If 80 percent rides one carrier, going direct on it saves about 12,000 a year, against an integration that costs several times that to build well and a recurring maintenance tax forever. At that volume the answer is usually still "buy, revisit at the next doubling." At two million labels with the same concentration, the same arithmetic funds a maintained integration several times over, and direct on the volume lane becomes the obvious move, with the aggregator kept for the long tail.

Two non-financial factors legitimately override the arithmetic. Carrier capabilities the aggregator does not surface, specialized services, regional carriers absent from its catalog, custom contract features, can force a direct integration at any volume, and this is common outside the US and EU where aggregator carrier coverage thins. And platform risk cuts both ways: an aggregator in your critical path is a dependency, but so is a homegrown integration whose author left; the honest comparison is between the provider's reliability record and your team's realistic ability to staff maintenance for years.

The build versus buy inputs, made concrete

3 to 8 cents Typical aggregator per-label fee band Often with free monthly tiers at the bottom and negotiated rates at volume. Multiply by annual labels to get the budget a direct build must beat.

4 to 10 weeks A single direct carrier integration, done properly Certification, sandbox quirks, edge cases, monitoring. Per carrier, before the permanent maintenance claim begins.

80 percent The concentration that makes direct worth modeling Fee savings only materialize on carriers you take direct. Concentrated volume converts; an even spread across many carriers does not.

The bottom line: route yourself in three questions

The shipping API decision compresses well. What is your annual label volume and how concentrated is it? Under roughly half a million labels a year, or spread across many carriers, the aggregator fee is cheaper than the engineering it replaces, and the decision is really just which aggregator prices your lanes best. Concentrated volume in the high six figures and up is where the hybrid pattern, direct on the volume lane, aggregator for the tail, starts funding itself.

Do you ship internationally, and from where? Cross-border customs handling is the strongest single reason to buy rather than build, and regional carrier coverage is the strongest single reason the answer differs by geography: teams shipping from Southeast Asia, for example, routinely find their dominant local carriers missing from US-centric aggregator catalogs and end up integrating one regional carrier directly alongside an aggregator, the hybrid pattern arriving earlier than volume alone would justify.

And who maintains it in year three? An integration is not a project that ends; carrier APIs change, providers get acquired, volume moves. The teams that are happy with their shipping stack years later are the ones that placed the internal service seam early, kept their own shipment table, and let the provider mix evolve behind it. The teams that are unhappy wired a provider SDK through their codebase in week one and have been paying for it since.

If your parcel volume is real and your workflows are standard, buy the aggregator, place the seam, and spend your engineering elsewhere. If your lanes are concentrated, your geography is underserved, or your fulfillment logic is genuinely unusual, the same seam is where a direct integration or a custom routing layer slots in, and that is engineering worth doing well, once, deliberately.

Your shipping stack, routed

How should your team integrate shipping?

• Under ~500k labels a year, standard workflows, any carrier mix

  One aggregator behind an internal shipping service seam

  The per-label fee is cheaper than the engineering it replaces, and the seam keeps the provider swappable when volume changes the answer.

• High volume concentrated on one or two carriers, contract rates in hand

  Hybrid: direct on the volume lanes, aggregator for the tail

  The fee savings on concentrated lanes fund the maintained integrations; the aggregator keeps breadth and failover for everyone else.

• Dominant local carriers missing from aggregator catalogs, or carrier features the aggregator hides

  Direct on the uncovered carrier, aggregator alongside where it helps

  Coverage gaps and capability gaps are legitimate overrides at any volume; the seam lets both paths coexist cleanly.

• Rental, returns-heavy, multi-warehouse or otherwise unusual fulfillment logic

  Custom routing and orchestration over bought carrier connectivity

  Buy the commodity (carrier connectivity), build the differentiator (your routing and promise logic). Almost never build the connectivity itself.

Three questions that settle the aggregator, direct, or hybrid call for most teams.

Frequently asked questions

A shipping API turns rates, labels and tracking into code, and the hard part is the seam you place around it. When your parcels need routing the platforms cannot model, work with AgileTech, a logistics engineering partner in Hanoi that builds the carrier integrations, orchestration layers and reconciliation machinery real fulfillment runs on.