whereparcel

Stuck on integration? Have a question? The developer is standing by.

Bug Report Answered

UPS /v2/track batch limit changed? Docs say 5 items, API rejects 5 UPS tracking numbers

MailroomIQ Posted 2 comments

Posting here because the Reddit post didn't get any traction and unsure if this is still a supported product based on lack of response? I'm integrating WhereParcel's Tracking API into a shipping audit workflow and ran into something confusing.

According to the docs, /v2/track supports batching multiple tracking numbers (up to 5), and our implementation has been using that pattern successfully.

Request format:

{
"trackingItems": [
{
"carrier": "us.ups",
"trackingNumber": "..."
},
{
"carrier": "us.ups",
"trackingNumber": "..."
}
]
}
Authentication is working — the request reaches WhereParcel and is visible in the API dashboard.

However, when sending 5 UPS tracking numbers in a single synchronous /v2/track request, the API now returns:

INVALID_REQUEST

Maximum 1 item allowed per synchronous request for these carriers:
us.ups (5 requested)
The confusing part:

The public tracking API docs indicate up to 5 parcels per request.

Rate limits are nowhere near being exceeded.

Authentication is successful.

The carrier code (us.ups) appears to be the documented value.

Questions:

Is there currently a carrier-specific limitation where us.ups only supports one tracking item per synchronous /v2/track request?

If so, is this a recent API behavior change that hasn't made it into the docs yet?

Should integrations handle UPS by splitting into one request per tracking number, while continuing to batch other carriers?

Is there another recommended approach (webhooks, async tracking registration, etc.) for multiple UPS shipments?

I can obviously work around this by making singleton UPS requests, but I want to make sure I'm implementing against the intended API behavior rather than coding around an undocumented restriction.

Comments (2)

  1. MailroomIQ

    Looks like this is an abandoned project; no replies here, Discord, nor reddit since late April/early May, it looks like. Cancelled subscription, good luck everyone!
  2. help.whereparcel Admin

    Thanks for the detailed writeup — and sorry about the silence on Reddit. The service is very much alive; the issue is on our side, in the docs. 1. Yes, this is an intentional carrier-specific limit — and you found a documentation gap. /v2/track does accept up to 5 items per request, as documented. What isn't documented is that carriers served by our real-browser infrastructure are additionally capped at 1 item per synchronous request. UPS is one of them. The cap is summed across all such carriers in a request, not per carrier — so 1× us.ups + 1× us.fedex is also rejected. The reason: these carriers sit behind aggressive anti-bot protection, so a lookup runs through a real browser queue and takes tens of seconds. A synchronous response has to complete inside ~50s, so batching several of them reliably times out. We'd rather reject the request up front than bill you for a request that returns timeouts. 2. Yes, this changed recently (2026-07-31) and the docs were not updated. That's our mistake — we're correcting the /v2/track reference now to state the limit and list the affected carriers. 3. Your workaround is the intended behavior, not a hack. One request per UPS tracking number. You can still batch other carriers normally — and you can even mix, e.g. 1 UPS item + up to 4 non-browser-carrier items in the same request (5 total). Carriers currently under the 1-item rule: us.ups, us.usps, us.fedex, us.dhl, us.dhl.express, us.dhl.ecommerce, intl.ups, intl.usps, intl.fedex, intl.dhl, gb.royalmail, gb.evri, ca.ups, ca.fedex, de.ups, es.ups, ie.ups, au.post. This list follows our infrastructure, so treat it as subject to change rather than hardcoding it — the error message always names the exact carriers that triggered it. 4. For multiple UPS shipments, use POST /v2/webhooks/register — this is the recommended path. Up to 100 tracking items in a single call, processed asynchronously (no 50s ceiling). recurring: true keeps monitoring until delivery and pushes an update on every status change — for a shipping audit workflow this is almost certainly what you want, since it replaces repeated polling (typically 5–10 notifications per parcel instead of hundreds of /v2/track calls against your quota). recurring: false if you just want a one-shot async lookup. Results can also be pulled later in bulk via the webhook results search endpoint if you prefer to fetch rather than receive. So: singleton /v2/track calls are fine for one-off UPS lookups, but for an audit workflow processing many shipments, /v2/webhooks/register with recurring: true is the API we'd point you to.