When Your Logistics API Breaks at 100,000 Orders a Day

A pan-India 3PL we worked with was processing 1.5 million shipments a month when their order allocation system started dropping 3 to 4 percent of orders during peak windows. The engineering team traced it to rate limits on three simultaneous carrier APIs hitting their ceiling at the same time. The fix was a weekend of patching. The actual problem — twelve separate carrier integrations with no abstraction between them — had been building for three years. ONDC’s logistics network expansion has pushed this pattern into every D2C and logistics platform operating in India. The question is not whether you need a carrier abstraction layer. It is whether you build one before or after your first production incident at scale.

The Multi-Carrier Integration Trap

India’s logistics market is fragmented by design. Delhivery covers pan-India air and surface. Blue Dart owns premium time-definite. Shadowfax and Xpressbees dominate hyperlocal and quick commerce. Regional players like Ecom Express and Shadowfax handle specific geographies more reliably than nationals. A 3PL serving D2C brands across categories cannot use one carrier. It uses eight to twelve.

The naive approach is direct integration: one code module per carrier, each handling that carrier’s authentication, request format, response parsing, webhook schema, rate-limit behavior, and error vocabulary. This works at two carriers. At twelve, it is a maintenance obligation that compounds with every carrier that changes their API version, deprecates a webhook, or throttles differently during sale events.

The ONDC logistics network made this worse in a specific way. ONDC logistics requires that your platform expose and consume a Beckn-compatible logistics API contract, not a proprietary one. Delhivery went live on ONDC in 2025. Ekart followed. The network now routes logistics requests across providers dynamically. Platforms that had direct-only integrations had to retrofit an ONDC-compatible layer on top of existing code. Most of them did it wrong, producing a hybrid that satisfies neither the carrier directly nor the ONDC protocol cleanly.

What ONDC Logistics Actually Requires from Your API Layer

The Beckn protocol that underlies ONDC logistics operates on a publish-subscribe model with four core API calls: search, select, init, and confirm. Every logistics provider on the network exposes these endpoints. Every buyer-side application calls them. The network acts as the registry.

This means your platform needs to speak two languages simultaneously: the ONDC Beckn protocol for providers inside the network, and proprietary APIs for providers outside it. Delhivery is on ONDC. Blue Dart is not. Shadowfax is not. You cannot standardize on Beckn alone.

What you actually need is a carrier abstraction layer that normalizes across both worlds. It accepts a canonical shipment order format from your order management system, routes it to the appropriate carrier or ONDC provider, handles authentication and protocol differences internally, and returns a canonical tracking event format upstream. The callers of this layer never see carrier-specific schemas.

This is not a new idea. It is the same adapter pattern used in payment gateways, SMS providers, and cloud storage abstractions. The logistics sector in India simply adopted it later than most.

The Carrier Abstraction Layer That Prevents API Spaghetti

A carrier abstraction layer has four components.

The **canonical data model** defines the internal representation of a shipment, a tracking event, a delivery confirmation, and a return request. Every carrier adapter translates to and from this model. The canonical model is the contract between your order management system and the carrier layer. It never changes for carrier reasons.

The **carrier adapter set** contains one adapter per carrier or per carrier class. Each adapter handles authentication, request serialization, response parsing, and error translation for that carrier. The adapter also handles rate-limit backoff, retry logic with carrier-specific idempotency keys, and webhook signature verification. Adapters are isolated: a bug in the Blue Dart adapter cannot affect the Delhivery adapter.

The **routing engine** selects the carrier for each shipment based on rules: serviceability by pin code, product category restrictions, weight limits, time-in-transit SLA, carrier performance history, and cost. The routing engine is where your carrier selection logic lives, not in your order management system.

The **observability layer** emits a standard event for every carrier API call: carrier name, endpoint, latency, HTTP status, retry count, and shipment ID. This makes it possible to detect carrier degradation in real time, build SLA dashboards per carrier, and feed performance data back into the routing engine.

The 3PL we mentioned rebuilt their integration layer around this architecture over six weeks. Carrier onboarding time dropped from three weeks per carrier to four days. API-related order drops went from 3 to 4 percent to under 0.2 percent. The team that had been maintaining carrier integrations was redeployed to routing logic and analytics.

The Logistics API Contract Scorecard (LACS)

Before building or auditing a carrier abstraction layer, use the LACS to evaluate each integration against five dimensions. Score each dimension from 1 (absent) to 4 (production-grade).

**1. Canonical compliance.** Does the carrier adapter translate fully to and from the canonical data model, with no carrier-specific fields leaking into upstream systems? Score 4 if the OMS never touches a carrier schema. Score 1 if OMS code references carrier field names directly.

**2. Idempotency handling.** Does the adapter generate and store idempotency keys for all write operations (create shipment, request pickup, initiate return)? Does it replay safely on timeout without creating duplicate shipments? Score 4 if tested with forced network partitions.

**3. Rate-limit resilience.** Does the adapter implement carrier-specific rate-limit backoff with jitter? Does it queue requests during degradation rather than dropping them? Score 4 if you have never had a rate-limit-caused order drop in production.

**4. SLA observability.** Does the abstraction layer emit latency, error rate, and retry count per carrier per endpoint, queryable in real time? Score 4 if you can identify carrier API degradation within 90 seconds.

**5. ONDC compatibility.** Can the layer route to ONDC Beckn-protocol providers without changes to the upstream order management system? Score 4 if ONDC routing is transparent to the OMS.

Carriers scoring below 8 total points across these five dimensions are integration liabilities. Prioritize refactoring them before adding new carriers on top of the same pattern.

Where the Hard Problems Live: Address Standardization, SLA Enforcement, and Fallback Routing

Three integration problems consistently break logistics APIs in India at scale.

**Address standardization.** Indian address data is unstructured. Customers enter addresses in free text. Different carriers accept different address formats. The Delivery Address Parsing problem requires a preprocessing step before any carrier API call: normalize the address to pin code, city, district, and state using a validated geocoder, and strip ambiguous landmarks from the primary address field. Carriers that reject malformed addresses silently return a “serviceability unavailable” response, which looks like a genuine serviceability gap but is an address data quality failure. The 3PL we worked with was misrouting 7 percent of shipments to secondary carriers due to this exact failure mode.

**SLA enforcement.** Carrier SLAs in India are contractual, not technical. If a carrier commits to 2-day delivery for a pin code tier and misses it, the recourse is a manual dispute process. The engineering solution is SLA shadow tracking: your abstraction layer predicts expected delivery at order creation time, monitors carrier scan events, and fires an alert when a shipment falls 12 hours behind its predicted path. This gives you data to support SLA breach claims and feeds into carrier selection weightings for future orders.

**Fallback routing.** Peak periods break single-carrier strategies. When your primary carrier suspends pickup in a region during a sale event, you need a fallback order. The routing engine should maintain a priority-ordered fallback list per pin code tier and switch automatically when the primary carrier’s real-time serviceability check fails. This requires testing fallback paths in staging regularly, not just in production when the primary carrier is down.

What This Means for Logistics and Supply Chain Leaders

If your platform currently has direct integrations to more than four carriers, you are carrying technical debt that compounds with scale. The ONDC logistics expansion makes it worse: you will need ONDC compatibility for an increasing share of your carrier base, and bolting Beckn protocol support onto direct integrations produces fragile code.

Three things you can do this week without engaging anyone externally. First, audit your current carrier integrations and document how many upstream systems have carrier-specific field references. That number is your abstraction debt score. Second, check whether your platform emits per-carrier API latency and error rates to a dashboard. If it does not, you are operating blind on carrier health. Third, test your fallback routing logic in staging by marking your primary carrier for three major pin code clusters as unavailable. If orders do not reroute automatically, your fallback configuration is a documented plan, not a working system.