Shipping API Delivery Status: Status Codes, Webhooks, and Exception Alerts

A shipping API delivery status describes a parcel’s progress, not whether an API request succeeded. To build reliable tracking, keep HTTP response codes separate from shipment statuses, process webhooks without assuming they arrive once or in order, and turn actionable exceptions into alerts with clear owners. For engineering and ecommerce operations teams, the goal is a shipment record that remains trustworthy when carrier updates are delayed, duplicated, or corrected.

This guide explains how to structure that record, handle incoming tracking events, and distinguish a delivery problem from a tracking integration problem.

Separate HTTP codes, API results, and shipment statuses

The phrase “status code” can refer to three different layers. Mixing them creates misleading dashboards and unnecessary customer notifications.

Layer	What it tells you	Example interpretation
HTTP response	The result of the HTTP request	A 200 response indicates HTTP-level success; it does not mean the parcel was delivered.
API business result	Whether the requested operation succeeded under the provider’s application rules	A response body may report that a tracking registration was rejected, including within a successful HTTP response if the API uses that design.
Shipment status	The reported physical or operational state of the parcel	In transit, awaiting collection, or delivered.

The HTTP semantics standard defines HTTP response meanings. For example, 202 Accepted means a request was accepted for processing, but processing has not necessarily finished. It is not evidence that a carrier has accepted a parcel.

Likewise, a failed tracking request does not prove that a shipment has stopped moving. Your application may temporarily lose visibility while the physical delivery continues normally. Monitor these layers independently.

Create a status model without discarding carrier detail

There is no universal numeric delivery-status code shared by every shipping API and carrier. A value from one integration should not be interpreted using another provider’s mapping. Use the documentation for the specific API version you implement.

A practical internal model combines a small set of normalized statuses with the original carrier event. Normalization supports consistent reporting; the original event preserves the detail needed for investigation.

Illustrative internal status	Meaning	Operational caution
Information received	Electronic shipment information exists.	Do not treat label creation as confirmed physical handover.
In transit	The tracking record indicates movement through the delivery network.	This broad category may include different transport stages.
Out for delivery	The parcel is reported on a delivery route.	Do not turn this into an unconditional delivery guarantee.
Awaiting collection	The recipient is expected to collect the parcel.	Include collection instructions or deadlines only when supported by the source.
Delivered	The tracking source reports delivery.	A delivery scan does not, by itself, resolve a customer’s nonreceipt claim.
Exception	An event may require attention or interrupt normal progress.	Retain the reason rather than treating every exception as lost.
Return in progress or returned	The parcel is moving back or has a reported return completion.	Keep return progress distinct from delivery to the original recipient.
Unknown	The available information cannot be mapped confidently.	Investigate the mapping or data gap rather than inventing a delivery state.

These labels are a suggested application model, not an official 17TRACK code list. Preserve the provider’s status code, substatus, description, event time, timezone information, location, and receipt time where available. Also retain the mapping version so that later mapping changes can be audited.

For a multi-carrier implementation, 17TRACK Tracking API is a relevant integration option. Use its official API documentation to establish the implementation contract rather than copying illustrative labels into provider-specific fields. Confirm the applicable status definitions, webhook configuration, authentication requirements, and response semantics before building the adapter.

Build webhook handling around durable receipt

A webhook is an HTTP request sent to your endpoint to report an event. It can reduce the need for repeated polling, but it should not be treated as a guarantee of immediate, ordered, or exactly-once delivery. Design the receiver to tolerate retries, interruptions, and unexpected payloads unless the provider explicitly guarantees otherwise.

1. Authenticate the request. Apply the provider’s documented verification method. If signatures are supported, validate them using the specified algorithm and raw request bytes. Do not invent a signature header or assume every service uses HMAC.
2. Validate the payload. Check required fields, types, payload size, and the association with a shipment your account manages. Handle unknown optional fields without unnecessarily breaking forward compatibility.
3. Persist before acknowledging. Store the accepted event or place it in a durable queue before sending the documented success response. If persistence fails, do not acknowledge the event as safely received.
4. Process asynchronously. Perform status mapping, order updates, and notification decisions outside the request handler where practical.
5. Make side effects idempotent. A repeated event should not create another support ticket or send another copy of the same customer message.

The exact acknowledgement code, timeout, retry schedule, and replay behavior depend on the provider. Check those details explicitly. A generic instruction to “return 200” is not a substitute for the webhook contract.

Use HTTPS and keep credentials out of URLs and routine logs. Apply access controls to stored payloads because tracking data may contain personal information. The OWASP REST Security Cheat Sheet provides relevant guidance on transport protection, input validation, and endpoint security.

Deduplicate events without suppressing real updates

Prefer a documented, stable event identifier when one is available. Otherwise, derive a deduplication key from a carefully selected combination of shipment identity, event timestamp, event code, and location. Test this approach against actual payloads: two legitimate events can share a timestamp, and the same event may arrive with slightly different descriptive text.

Use separate deduplication controls for event ingestion and downstream actions. A status update might need to be stored again as a correction while its customer notification should remain suppressed. Give each notification or ticket action its own durable identity.

Keep event time separate from receipt time

Suppose an in-transit event reaches your system after an out-for-delivery event, but its carrier timestamp is earlier. Store it in the history without automatically changing the current status back to in transit.

Timestamp ordering alone is not sufficient for every case. Missing timezones, corrected scans, and conflicting sources require explicit rules. Preserve timestamp precision and offsets, record when your system received each event, and use documented provider sequence information where available. Do not impose a rigid forward-only status ladder: delivery attempts, redirections, returns, and corrections can create legitimate transitions that appear to move backward.

Turn exceptions into owned actions

An exception alert should explain what happened, what action is needed, and who owns the next step. A generic “shipment exception” message leaves operations staff to repeat the same investigation and can alarm customers without helping them.

Start with a small routing policy:

• Address or access problem: Route to customer support to verify the issue and check the carrier’s available correction process. Do not promise an address change before confirming it is possible.
• Collection required: Notify the recipient when the source provides a usable collection instruction. Preserve any verified deadline.
• Customs action required: Assign the case according to who must provide the requested documents or information. A customs-related event alone does not establish that payment is due.
• Unsuccessful delivery attempt: Check the reported next step before advising redelivery or collection.
• Return to sender: Open an operations review. Do not automatically issue a refund solely from a broad tracking label unless your policy explicitly authorizes it.
• Carrier-reported loss or damage: Route to the claims owner and preserve the event evidence. Keep claim decisions separate from general delay detection.

Each alert should carry a shipment identifier, order reference, event reason, source timestamp, latest known state, assigned owner, and next action. Include a link to the relevant internal record instead of exposing unnecessary customer details in shared messaging channels.

Treat “no update” as a separate condition

A shipment with no recent scan is not automatically lost. It may be between checkpoints, awaiting its first physical scan, or affected by a visibility gap.

Define inactivity thresholds by service, route, shipping stage, and business commitment rather than applying one universal timer. Distinguish a parcel that has never received an acceptance scan from one that stopped updating after network entry. If historical evidence is limited, use the threshold to trigger investigation, not to declare loss.

Suppress repeat alerts while an unchanged case remains open. Escalate when new evidence appears, an agreed follow-up is missed, or the customer delivery commitment requires intervention.

Monitor integration health separately from delivery performance

API monitoring answers whether your tracking integration is functioning. Delivery monitoring answers what is happening to shipments. A healthy endpoint can receive stale carrier data, while an unavailable endpoint can miss updates for parcels that are moving normally.

• Request health: Track authentication failures, timeouts, rate-limit responses, server errors, and application-level rejections.
• Webhook health: Track verification failures, acknowledgement latency, persistence failures, duplicate deliveries, and processing errors.
• Processing health: Monitor queue age, unprocessed events, mapping failures, and notification failures.
• Tracking freshness: Measure time since the last source event separately from time since your last successful ingestion.
• Operational outcomes: Track unresolved exceptions, time to ownership, and overdue follow-ups.

For request retries, follow the provider’s rate-limit and retry guidance. Avoid blindly repeating operations that could create duplicate registrations or other side effects; use documented idempotency mechanisms where available.

Where supported, use a reconciliation process to retrieve the latest tracking record after outages or suspected missed events. Set its frequency within contractual limits and rate limits. Webhooks and reconciliation serve different purposes: one delivers changes, while the other helps detect and repair gaps.

Test failure cases before enabling customer notifications

Start with internal-only processing and inspect representative shipments before allowing status changes to send customer messages. Test more than the normal progression from in transit to delivered.

• A duplicate webhook creates one intended customer notification.
• An older event arriving late does not incorrectly replace the current state.
• An unknown status is retained and flagged rather than silently mapped to delivered.
• A failed durable write does not produce a successful acknowledgement.
• A temporary downstream outage leaves events available for retry.
• A delivered event followed by a correction remains auditable.
• A multi-parcel order does not become fully delivered when only one parcel is delivered.
• An API outage alerts engineering without automatically telling customers their parcels are delayed.

The release criterion should be operational consistency: the shipment record, customer message, and support action must agree with the same underlying evidence. A successful webhook response alone does not demonstrate that the delivery experience is working.

FAQ

Does HTTP 200 mean the package was delivered?

No. It indicates HTTP-level success for the request. Read the API’s business result and shipment-status fields separately. For a webhook, a successful acknowledgement concerns receipt of the notification, not physical parcel delivery.

Should I use webhooks or polling for tracking updates?

Use webhooks for event-driven updates when the provider supports them. Where supported and operationally justified, add bounded reconciliation polling to recover gaps. Polling alone may be appropriate when webhooks are unavailable, but its frequency must respect the provider’s limits and your freshness requirements.

Why can the tracking status change after “delivered”?

A source may correct an event, or your integration may receive delayed or conflicting information. Preserve the history and evaluate the newer evidence rather than treating delivered as technically immutable. A reported delivery and a customer’s confirmation of receipt are also different facts.

How quickly should an exception alert be sent?

Base urgency on the required action and any verified deadline. An issue requiring recipient action deserves different handling from an informational delay. Processing speed cannot compensate for a carrier event that was published late, so preserve both source and receipt timestamps.

Should customers see the raw carrier status?

Usually, customers benefit from a clear explanation and a supported next step rather than an unexplained code. Retain raw details for support and audit purposes. Never simplify a status into a stronger promise than the underlying event supports.

Sources

• RFC 9110: HTTP Semantics — reference for HTTP status-code meanings, including 200 and 202.
• OWASP REST Security Cheat Sheet — security guidance relevant to API and webhook endpoints.
• 17TRACK Tracking API — official product reference for the tracking integration option discussed.
• 17TRACK API Documentation — official reference for provider-specific integration requirements; illustrative schemas and workflow recommendations in this guide are not a substitute for that contract.