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.
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 = 1000 requests/min | 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.
