Courier partner API

SELECT QURIER

after courier allocated order will show in ready to ship

Excellent question, Pavan 👏 — this is a key challenge in logistics aggregator platforms like Shiprocket, because they rely on unreliable third-party courier APIs that can fail, time out, or return inconsistent data.

Let’s go step by step on how Shiprocket (or any similar aggregator like Pickrr or NimbusPost) handles API failures robustly while maintaining reliability and good user experience 👇

⚙️ 1. Retry Mechanism (with Backoff)

When a booking or tracking API call to a courier partner fails, Shiprocket does not fail the entire workflow immediately.

Instead, they implement:

• Automatic retries using exponential backoff Example: Retry after 2s → 4s → 8s → 16s (max 3–5 attempts)

• Circuit breaker pattern — if multiple requests to the same courier keep failing, temporarily stop calling that courier’s API and mark it unavailable.

🧠 Tools used:

• Retry libraries (e.g., Resilience4j, or in Go/Rust custom retry logic)

• Background job queues (like Celery, Sidekiq, or Kafka consumers)

📨 2. Queue-Based Request Handling

Every courier API call (like Create Shipment, Track Order) is not synchronous — it goes through a message queue.

Flow:

1. Order request enters Kafka/RabbitMQ queue

2. Worker service picks it up and sends API request to courier

3. If the courier API fails → worker retries or requeues the message with delay

4. Status stored in DB as pending_retry

This ensures no data loss and eventual consistency, even if couriers are down temporarily.

🧩 Benefit: API failure doesn’t block the user. Seller immediately gets a “shipment under processing” response while retries happen in the background.

💾 3. Fallback to Alternate Courier

If a courier consistently fails (API timeout or bad response), Shiprocket can:

• Re-route the shipment request to another available courier based on pre-defined rules:

  • Cheapest available

  • Fastest available

  • Reliable score (historical SLA success rate)

This logic is implemented inside the Courier Selection Engine, which maintains health scores for each courier partner.

📊 4. Failure Logging & Monitoring

All failed API interactions are logged in detail:

• Courier name

• Request payload

• Response or error

• Retry count

• Last attempt time

These logs feed into:

• ELK Stack (Elasticsearch + Kibana) for search

• Prometheus + Grafana dashboards for metrics like:

  • API success rate per courier

  • Latency

  • Failure trend

📢 Alerts are sent (Slack/Email) if a courier’s API failure rate crosses a threshold (e.g., 10% in last 5 minutes).

🧰 5. Dead Letter Queue (DLQ)

If all retry attempts fail (e.g., courier API is down for hours):

• The message is pushed into a Dead Letter Queue

• The operations/support team manually reviews and reprocesses these shipments later

This prevents permanent data loss and ensures manual intervention is possible.

🧩 6. Idempotency & Duplicate Handling

Since retries can lead to duplicate API calls, Shiprocket uses idempotency keys:

• A unique key (like order ID or AWB request ID) is sent with each API call.

• If the courier processes the same request again, it safely ignores duplicates.

This avoids accidental multiple bookings or charges.

🔒 7. Transactional Integrity

Important steps (booking, label generation, tracking update) are handled via transactional states in DB:

order_status = [CREATED, BOOKING_PENDING, BOOKED, FAILED, RETRYING, COMPLETED]

This ensures the system knows exactly where the failure happened and can resume safely.

🔁 8. Async Tracking Updates

Tracking updates are not dependent on live API calls. Shiprocket uses:

• Webhooks (preferred, near real-time)

• Polling (backup) — if webhooks fail or are delayed, Shiprocket polls every X minutes to keep status fresh.

This ensures that tracking reliability is high even if some courier’s webhook system is unstable.

🧠 Example Scenario

Case: Booking with Delhivery API Fails

1. Shiprocket sends POST /shipments to Delhivery API → Timeout

2. Retry after 5s → Still fails

3. Retry again after 20s → Success ✅

4. Status in DB changes from BOOKING_PENDING → BOOKED

5. Label generated and sent to seller

If all retries fail → fallback to XpressBees → label regenerated.

💡 Summary Table

Would you like me to draw a diagram of this failure-handling architecture (showing queues, retry flow, DLQ, etc.)? It’s a great visual for understanding how such systems maintain reliability.

Perfect follow-up, Pavan 👏

When Shiprocket connects to multiple third-party courier APIs, there are a lot of things that can go wrong — both from Shiprocket’s side (bad data, wrong payload) and the courier’s side (downtime, throttling, etc.).

Here’s a breakdown of the most common reasons API requests fail in such logistics integrations — grouped by type 👇

⚙️ 1. Client-Side (Shiprocket) Issues

These happen when Shiprocket sends something invalid or incomplete to the courier API.

🧩 2. Courier-Side (Third-Party API) Issues

These are issues with the courier partner’s systems — Shiprocket can’t control them but needs to handle gracefully.

🧰 3. Network / Infrastructure Issues

Problems in the communication path between Shiprocket and courier systems.

📦 4. Data Integrity / Business Logic Issues

When the API request itself succeeds technically, but the business validation fails.

🧠 5. Shiprocket Internal Service Issues

Failures within Shiprocket’s microservices before the request even reaches the courier.

🧩 6. Tracking API-Specific Failures

Tracking is continuous, so failures here are also common.

📈 7. Integration Lifecycle Issues

These occur during or after new courier integration.

⚙️ In Real Life

Shiprocket logs error categories and response codes in a central monitoring system (like ELK + Grafana). They often have dashboards such as:

Courier API Success Rate (Last 24h)
-----------------------------------
Delhivery      97.2%
Xpressbees     99.1%
Bluedart       94.5%
EcomExpress    96.8%

Anything below ~95% triggers an alert and retries are automatically managed through queues.

🧩 In Short

Common reasons API requests fail in Shiprocket:

Would you like me to show a real-world flow diagram of how Shiprocket retries + classifies these failures (e.g., failed → retry → DLQ → manual fix)? It’s a great visual to understand resilience in logistics APIs.