What Is a Shipping API and How Do You Integrate It?

March 26, 2026 · 6 min read

A shipping API exchanges data between your order system and a shipping service. It can support labels, rate requests and tracking updates. Check the available endpoints against your requirements: not every API supports the same operations.

Related reading: shipping API page.

4 Core Functions of a Shipping API

1. Rate Query (Rate API)

Used to show customers real shipping costs at checkout or to select the cheapest carrier after an order is placed.

What you send:

  • Sender city/district
  • Recipient city/district
  • Package dimensions and weight
  • Service type (standard, express, cash on delivery)

What you get back:

  • Shipping cost
  • Estimated delivery time
  • Additional service fees (insurance, COD commission)

Practical use: Instead of charging a flat shipping fee, you can show real-time rates at checkout — "Carrier A — $12, 2-3 business days." This improves both margins and customer trust.

2. Shipment Creation & Label Printing (Shipment API)

This is where the real work happens. After an order is confirmed, you create a shipment and get a printable label.

What you send:

  • Sender/recipient details (name, address, phone)
  • Package details (weight, dimensions, quantity)
  • Cash on delivery amount (if applicable)
  • Service type

What you get back:

  • Tracking number (barcode)
  • Label file (PDF or ZPL format for thermal printers)

Key detail: Label format matters. If your volume is low, A4 PDF works fine. At 50+ shipments per day, thermal printer + ZPL format saves serious time — each label prints in 2 seconds.

3. Tracking (Tracking API)

Used to check shipment status after a label is created.

What you send: Tracking number

What you get back:

  • Current status (accepted, in transit, out for delivery, delivered)
  • Status history (timestamped)
  • Delivery proof (recipient name, signature)

Two approaches:

Polling (You ask)Webhook (Carrier tells you)
How it worksYou query the API every X minutesCarrier POSTs to your endpoint on status change
LatencyDepends on query interval (5-30 min)Instant (seconds)
Server loadHigh — 90% of queries return no changeLow — requests only on actual changes
Scalability1000 active shipments ≈ 288,000 requests/day (5-min interval)1000 active shipments ≈ 3000 requests/day (avg. 3 status changes)

Always prefer webhooks. But not every carrier supports them — in that case, poll smart: query new shipments hourly, shipments older than 3 days once daily.

4. Cancellation & Returns (Cancel/Return API)

  • Cancel a shipment before pickup
  • Generate return labels
  • Track return shipments

The Reality of Carrier APIs

Every Carrier's API Is Different

This is the biggest headache. Carriers don't follow a unified API standard:

CarrierProtocolAuthenticationData Format
Carrier ASOAP (XML)Username/passwordXML
Carrier BRESTAPI KeyJSON
Carrier CSOAPUsername/passwordXML
Carrier DRESTOAuth 2.0JSON

Why this matters: code that works with Carrier A won't work with Carrier B. For each carrier you need:

  • Different request structures
  • Different error codes (Carrier A's "102" and Carrier B's "ERR_ADDRESS" might mean the same thing)
  • Different test environments (some don't even have a sandbox)
  • Different documentation quality (some provide Swagger, others a Word document)

SOAP vs REST: Practical Difference

Older carriers typically use SOAP:

  • You need to parse XML
  • Download a WSDL file and generate a client
  • Error messages come wrapped in XML CDATA — hard to debug

Modern carriers use REST + JSON:

  • Readable request/response
  • Easy to test in Postman
  • Standard HTTP status codes for errors

How Long Does a Real Integration Take?

Honest table — time a backend developer spends per carrier:

PhaseDurationNotes
Documentation & API discovery1-2 days3-4 days if docs are poor
Core functions (label + tracking)3-5 daysLonger for SOAP
Error scenarios & edge cases2-3 daysWrong address, timeout, character encoding
Testing (sandbox + real shipment)2-3 daysNo sandbox = must test with real shipments
Production deployment & monitoring1-2 daysLogging, alerting

2-3 weeks per carrier is realistic. For 5 carriers, timelines don't multiply linearly (shared infrastructure), but you're still looking at 2-3 months.

Maintenance isn't included: API changes, certificate renewals, new service types — these require a few days per carrier annually.

Single API for All Carriers: The Aggregator Approach

Instead of integrating each carrier yourself, you can use an aggregator (multi-carrier platform) that wraps all carrier APIs behind a single standardized API.

How it works:

  1. You send requests to the aggregator in a single format
  2. The aggregator translates to the carrier's format
  3. Carrier response is normalized and returned to you

What you gain:

  • No SOAP/REST, XML/JSON differences to deal with
  • Standardized error codes
  • Adding a new carrier = a config change, not a code change
  • Built-in rate comparison — get quotes from 5 carriers in one request

What you lose:

  • No full control over the carrier API
  • Dependency on the aggregator (if they go down, so do you)
  • Every request goes through the aggregator (adds milliseconds)

Should You Build Your Own or Use a Platform?

This depends on your business:

Build it yourself if:

  • You have a dev team with backend capacity
  • You only need 1-2 carriers
  • You have very specific business rules (e.g., custom parameters to carrier APIs)
  • You want full control and independence

Use a platform if:

  • You work with 3+ carriers
  • Developer resources are limited or shipping isn't your core focus
  • You want to start in days, not months
  • You don't want to maintain API integrations

Shipink's API is REST-based and provides access to 16 carriers through a single endpoint. You can use your own contracts or platform rates.

Technical Checklist Before Going Live

Security

  • API keys in environment variables, not in code
  • HTTPS enforced (no HTTP requests)
  • IP whitelist active (if carrier supports it)
  • API keys have minimum required permissions

Error Handling

  • Reasonable timeout (10-30 seconds, depending on operation)
  • Retry mechanism for transient errors (5xx, timeout) with exponential backoff
  • Meaningful user messages for permanent errors (4xx)
  • All API calls logged

Performance

  • Request queue to avoid rate limits
  • Rate queries cached (15-30 min validity for same route)
  • Label creation async (customer not blocked)

Monitoring

  • API response times tracked
  • Error rate alerts configured
  • Per-carrier success/failure rates on dashboard

Putting This Into Practice

After the first label, test retries, cancellations and tracking updates. Keep errors traceable and prevent a repeated request from creating another shipment.

Related pages: carrier integration: build vs buy, Shopify, WooCommerce, Ticimax, how to choose shipping software, shipping API documentation.

Frequently Asked Questions

What is a shipping API, in one sentence?
A shipping API is the interface that lets your e-commerce system talk to a carrier programmatically: query rates, create shipments, generate labels, read tracking status, and drive returns — all without anyone touching a panel.
How long does a shipping API integration take?
For a single carrier, 2-3 weeks is realistic for an experienced team; documentation quality and whether a sandbox exists decide the number. Three carriers doesn't scale linearly but lands near two months — plus ongoing maintenance forever after.
Should I build my own integration or use an aggregator?
With 1-2 carriers and a strong technical team, building it yourself gives full control. At three or more carriers an aggregator is almost always the better call: you stop dealing with SOAP/REST and error-code differences, and adding a carrier becomes a config change rather than a code change.
Should I use webhooks or polling?
Webhooks wherever they're available. Polling every shipment on a fixed interval generates wasted requests and tells you about status changes late. If webhooks aren't supported, tier your polling interval by shipment state — query parcels out for delivery often, and delivered parcels never.
What's the most common mistake in shipping API integrations?
Leaving error handling until later. The happy path works in two days; the real work is what you do on timeouts, invalid addresses, capacity rejections, and retryable failures. Without that layer, shipments fail silently and you hear about it from the customer.
How should I merchant API keys?
Never in your repository or in frontend code. Keep them in environment variables or a secret manager, separate production from test credentials, and rotate them regularly. A leaked carrier API key is leaked authority to create shipments.

Shipping? We take care of it

Every e-commerce company has different shipping operations, needs and problems. Let our team explain to you how we specifically solved these problems.

Request a demo
Shipink truck