Skip to main content
HomeBlogGuidesHow to Send Multiple Tracking Numbers in One API Request (Batch Limits & Partial Failures)

How to Send Multiple Tracking Numbers in One API Request (Batch Limits & Partial Failures)

17TRACK

To send multiple tracking numbers in one API request, use a Tracking API endpoint that explicitly accepts a batch, format each shipment according to its request schema, and split larger lists into batches within the documented limits. Then inspect both the HTTP response and each shipment’s result: a successful HTTP request does not necessarily mean every tracking number was accepted. Retry only eligible failures, and reconcile uncertain outcomes before resubmitting a whole batch.

How to Send Multiple Tracking Numbers in One API Request

This guide is for developers connecting shipment tracking to an order management system, warehouse platform, ecommerce application, or internal dashboard. The objective is not simply to send fewer requests. It is to account for every shipment without creating duplicate work or losing failed records.

First, identify what the batch endpoint actually does

A tracking integration can involve several distinct operations. Registering shipments, retrieving their latest tracking information, and receiving subsequent updates are not interchangeable.

  • Registration: Submit shipments so the service can begin or maintain tracking for them.
  • Lookup: Request tracking information for shipments, subject to the endpoint’s retrieval rules.
  • Update delivery: Receive later changes through a supported mechanism, such as webhooks, or retrieve them through scheduled requests.

Check the documentation for the exact operation you need. A registration endpoint accepting multiple records does not establish that a lookup endpoint accepts the same number, uses the same schema, or shares the same rate limit.

For a 17TRACK integration, start with the Tracking API product page and use the official API documentation to confirm the operation, authentication method, request format, and response fields. Treat the examples below as implementation patterns, not as a substitute for that API contract.

Batch limits are more than a maximum number of shipments

There is no universal batch limit for a Tracking API. Limits can differ by provider, endpoint, API version, and account configuration. Before implementing batching, record these constraints separately.

ConstraintWhat to confirmImplementation consequence
Items per requestMaximum records for the specific operationSplit the input list before sending
Request body sizeAny documented byte limitAccount for optional fields and serialization size
Request rateAllowed requests over a defined intervalPace requests through a shared limiter
ConcurrencyAny simultaneous-request restrictionBound the number of active workers
Usage accountingWhether usage is counted by request, shipment, or another unitEstimate consumption separately from request volume

For example, if a hypothetical endpoint permits 25 records per request, 63 records require three requests containing 25, 25, and 13 records. These numbers illustrate chunking only; they are not stated 17TRACK limits.

Do not assume that batching reduces billable usage. It can reduce HTTP request overhead, but any effect on charges depends on the provider’s actual accounting rules. Similarly, a valid batch size does not authorize unlimited parallel requests.

Prepare records before building the request

Most avoidable batch failures start with input preparation. Validate each shipment before adding it to a batch, but avoid rules that accidentally reject legitimate tracking numbers from different carriers.

  1. Preserve tracking numbers as strings. Converting them to numbers can remove leading zeros or alter long identifiers.
  2. Remove accidental surrounding whitespace. Do not remove internal characters or change case unless the relevant specification permits that normalization.
  3. Validate required fields. Some workflows may require a carrier identifier or additional shipment information. Use only documented field names and values.
  4. Choose an explicit deduplication scope. A repeated tracking number is not automatically a duplicate across every carrier, merchant, or historical shipment.
  5. Keep a local shipment identifier. Store the relationship between the outbound item and your order or shipment record, even when the API does not accept custom reference fields.

For Carrier Tracking across multiple networks, do not infer the carrier solely from a tracking number’s length or prefix unless that inference is reliable for your specific workflow. Where the API supports carrier identification, follow its documented ambiguity-handling behavior.

Illustrative request structure

The following JSON shows the concept of a batch payload. The wrapper, property names, and identifiers are illustrative, not a 17TRACK request schema. Some APIs expect a top-level array instead of an object containing an array.

{
  "shipments": [
    {
      "tracking_number": "EXAMPLE000001",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    },
    {
      "tracking_number": "EXAMPLE000002",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    }
  ]
}

Build the payload through a JSON serializer rather than concatenating strings. Send authentication credentials through the documented mechanism, and keep them out of source control, browser-delivered code, and routine logs.

Process the response at two levels

A batch request has a transport-level outcome and an application-level outcome. Your integration must evaluate both.

Level 1: Did the request receive a usable response?

Start with the HTTP status, response headers, and response body. Authentication errors, malformed requests, rate limiting, and server failures may prevent normal item processing. A network timeout is different: the client may not know whether the server received or processed the request.

HTTP semantics are defined in RFC 9110. However, the provider’s documentation determines how its application-level result fields map to actual shipment outcomes.

Level 2: What happened to each shipment?

If the response supports item-level results, classify every submitted record. Do not assume that HTTP 200 means every record succeeded, or that a result list preserves request order unless the contract explicitly guarantees it.

  • Accepted: The operation succeeded according to the endpoint’s documented definition.
  • Permanent input failure: Correct or investigate the record before another attempt.
  • Retryable failure: Schedule another attempt under the provider’s retry guidance.
  • Unknown outcome: The response is missing, incomplete, or cannot be safely matched to the submitted record.

Keep “already registered” or similar duplicate-related responses separate until you understand their documented meaning. They may indicate that the desired state already exists, but they should not automatically be treated as successful ownership, configuration, or subscription confirmation.

After processing a response, every input record should have exactly one local outcome. A useful reconciliation check is: submitted records equal accepted records plus permanent failures plus retryable failures plus unknown outcomes. This is a local accounting rule, not a required API response format.

Handle partial failures without replaying successful records

Suppose an illustrative batch contains ten shipments: seven are accepted, two have invalid required fields, and one encounters a documented temporary error. Save the seven successful outcomes, route the two invalid records for correction, and retry only the temporary failure.

Replaying all ten records creates unnecessary traffic and can complicate duplicate handling. It also makes it harder to distinguish an original rejection from a later duplicate-related response.

OutcomeRecommended action
Invalid field or unsupported valueFix the input; do not retry unchanged
Authentication or permission failurePause affected work and repair credentials or access
Rate limit responseDelay according to documented guidance and applicable response headers
Temporary item-level errorRetry that item with bounded attempts and backoff
Timeout after submissionMark uncertain; reconcile or use documented retry-safety guarantees
Unrecognized or incomplete resultRetain evidence and investigate rather than assuming success

HTTP 429 denotes too many requests, and its response may include a Retry-After header, as described in RFC 6585. Do not assume that header is always present. When no explicit retry delay is supplied, use a bounded backoff policy consistent with the API’s documentation.

Add jitter to spread retries from multiple workers, set a maximum attempt count or retry age, and send exhausted records to a review queue. Retrying indefinitely can hide a persistent configuration problem.

Why timeouts need special treatment

A timeout does not prove rejection. The server may have accepted the batch before the connection failed. Automatically replaying a state-changing request can therefore repeat work.

If the endpoint supports documented idempotency keys, follow its rules, including key scope and retention. Do not invent an idempotency header and assume the server honors it. Otherwise, use a supported lookup or reconciliation workflow to determine whether the desired state exists before resubmitting. Local deduplication helps coordinate your own workers but does not guarantee server-side idempotency.

A practical batch-processing workflow

Keep provider-specific details in an adapter so the queue, retry scheduler, and monitoring logic do not depend on raw response field names.

validate records and retain local shipment IDs
resolve duplicates within the intended business scope
split records using documented item and payload limits

for each batch through a bounded worker pool:
    persist an attempt record before sending
    wait for the shared rate limiter
    send using the provider-specific adapter

    if the outcome is uncertain:
        enqueue reconciliation
        continue

    classify request-level and item-level outcomes
    persist one outcome for every submitted record
    schedule only eligible failures for retry
    route invalid or exhausted records for review

Make outcome persistence and retry scheduling recoverable. For example, a durable job record or transactional queueing pattern can prevent a process crash from losing the retry decision. When workers restart, they should be able to distinguish unsent work from work whose remote outcome is still uncertain.

Use batch size as a configurable setting tied to the relevant endpoint, not as a constant scattered throughout the codebase. A smaller batch may be useful when troubleshooting or isolating problematic records; the largest allowed batch is not automatically the best operating size.

Monitor shipment outcomes, not just HTTP uptime

API Monitoring should show whether shipments are reaching the intended state. A dashboard reporting only HTTP success rates can miss partial failures inside otherwise successful responses.

  • Item acceptance rate: Accepted records divided by submitted records, with a clearly defined treatment of retries.
  • Failure distribution: Counts by endpoint, documented error code, and relevant carrier context.
  • Unknown outcomes: Unreconciled records and how long they have remained unresolved.
  • Retry backlog: Pending retries, oldest retry age, and exhausted attempts.
  • Request health: Latency, timeouts, rate limiting, and server errors.
  • Tracking freshness: Whether accepted shipments subsequently receive usable tracking information.

Registration acceptance is not proof of a new carrier scan. Keep API processing status separate from shipment movement and data freshness so an integration incident is not confused with a delivery delay.

Log local batch IDs, shipment references, attempt counts, documented error codes, and provider request IDs when available. Redact credentials and unnecessary personal information. Use tracking identifiers only where operationally necessary, and avoid placing raw shipment identifiers in high-cardinality metric labels.

Test these cases before production

Use a documented sandbox or controlled test environment where available. Do not assume invented tracking numbers will produce predictable production responses.

  1. Submit a valid batch at the documented item limit, then test how your client prevents an oversized batch.
  2. Verify that tracking numbers with leading zeros survive serialization and storage.
  3. Test mixed accepted and rejected items without retrying successful records.
  4. Simulate rate limiting and confirm that multiple workers respect the same limit.
  5. Simulate a timeout after submission and verify the reconciliation path.
  6. Restart a worker between response receipt and local persistence.
  7. Test missing, unfamiliar, or unmatchable item results.
  8. Confirm that invalid records reach a visible correction queue instead of retrying forever.

A production-ready integration can explain the state of every submitted shipment, including those whose outcome is temporarily unknown. Reducing request count is useful; preserving that accountability is the more important design goal.

FAQ

How many tracking numbers can I send in one request?

Use the limit documented for the exact endpoint and API version. Also check request size, rate limits, and any account-specific constraints. There is no safe universal number to apply across tracking APIs or across different operations within one API.

Can one invalid tracking number cause the whole batch to fail?

Yes, depending on the endpoint’s validation rules. Some APIs return individual rejections, while others may reject a request before item processing. Check both request-level errors and item-level results; do not assume every batch endpoint supports partial acceptance.

Should I retry a batch when the HTTP response is successful?

Not automatically. Parse the documented application-level status and item results first. Persist successful records and retry only eligible failures. If the result cannot be interpreted safely, classify it as uncertain and investigate.

Can I mix carriers in the same batch?

Only when the endpoint supports that request structure. Confirm whether carrier information is supplied per shipment, whether automatic identification is supported, and what happens when identification is ambiguous. A multi-carrier service does not by itself establish every endpoint’s batching rules.

Does batching make tracking updates arrive faster?

Batching can reduce the number of requests your application sends, but it does not by itself make carrier events appear sooner. Registration, data retrieval, carrier scan availability, and update delivery are separate parts of the workflow.

Sources