A shipping API lets your e-commerce store talk to carriers programmatically. When an order comes in, create a label. When a status changes, notify the customer. When a return is requested, generate a return label. All of this happens through the API automatically.
This guide covers the technical structure of shipping APIs and the practical side of e-commerce integration.
If you'd rather use a ready-made API than build your own, our shipping API page lists the carriers reachable through one integration, along with the documentation. This guide is for seeing the technical picture before you decide.
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 works | You query the API every X minutes | Carrier POSTs to your endpoint on status change |
| Latency | Depends on query interval (5-30 min) | Instant (seconds) |
| Server load | High — 90% of queries return no change | Low — requests only on actual changes |
| Scalability | 1000 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:
| Carrier | Protocol | Authentication | Data Format |
|---|---|---|---|
| Carrier A | SOAP (XML) | Username/password | XML |
| Carrier B | REST | API Key | JSON |
| Carrier C | SOAP | Username/password | XML |
| Carrier D | REST | OAuth 2.0 | JSON |
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:
| Phase | Duration | Notes |
|---|---|---|
| Documentation & API discovery | 1-2 days | 3-4 days if docs are poor |
| Core functions (label + tracking) | 3-5 days | Longer for SOAP |
| Error scenarios & edge cases | 2-3 days | Wrong address, timeout, character encoding |
| Testing (sandbox + real shipment) | 2-3 days | No sandbox = must test with real shipments |
| Production deployment & monitoring | 1-2 days | Logging, 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:
- You send requests to the aggregator in a single format
- The aggregator translates to the carrier's format
- 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
Conclusion
Shipping API integration is the foundation of e-commerce automation. The biggest challenge is that carriers don't share a common API standard — mixed SOAP/REST, different error structures, and varying documentation quality.
If you work with 1-2 carriers and have a strong technical team, building your own integration gives you full control. If you need 3+ carriers or want to start quickly, an aggregator platform is the more practical path.
Whichever route you choose: prefer webhooks, take error handling seriously, and keep your API keys secure.
If you're weighing whether to build your own, carrier integration: build vs buy works through the maintenance math and the forced migrations.
There's also a no-code path to the same outcome: ready-made platform integrations speak the API for you. If you're on Shopify, WooCommerce, or Ticimax, start from those integration guides. We cover the platform decision itself in how to choose shipping software.
You can start by browsing the shipping API documentation.
