Multi-carrier shipping API: what it must solve
A useful API does more than return PDFs: it preserves identity, prevents duplicate purchases, tolerates partial failures and exposes reconcilable states.
Updated: 2026-08-01
Key takeaways
- Quoting and purchasing should be separate operations.
- Every purchase needs a stable idempotency key.
- Webhook retries must not duplicate effects.
- Retain both raw and normalized provider responses.
Minimum flow
- Validate origin, destination, parcel and units.
- Request options and show price, service and estimate.
- Select an identifiable option, not only a name.
- Purchase with an order-level idempotency key.
- Store reference, tracking, label and status.
- Consume webhook updates and reconcile.
Why idempotency is mandatory
A late response does not mean the purchase failed. Retrying with a new key can buy two labels. The same logical operation must reuse a stable key, and the server should return the previous result when it already exists.
Do not use a fresh timestamp for every retry. The key should identify the commercial attempt, not the HTTP request.
Partial failures and timeouts
In multi-carrier rating, one slow provider should not erase every other option. Return partial results with structured warnings and an overall time budget.
A purchase timeout is ambiguous: query status or reuse the same idempotency key first. Blind retries are how duplicate labels get purchased.
Data and observability
- Separate internal and external IDs.
- Currency, value and price breakdown.
- Provider, service and selected option.
- Normalized state plus original response.
- Correlation ID per operation.
- Logs without credentials or unnecessary personal data.
Frequently asked questions
- Should I store the PDF?
- Keep at least a durable reference and a retrieval strategy. Review expiration and permissions of provider URLs.
- What should a duplicate webhook do?
- Produce the same final state without creating another movement, email, label or charge.