Skip to main content
HomeBlogGuidesHow to Register a Tracking Number via API: Request Fields, Carrier Codes, and Responses

How to Register a Tracking Number via API: Request Fields, Carrier Codes, and Responses

17TRACK

To register a tracking number via API, send an authenticated registration request containing the shipment’s tracking number and, when required, a carrier identifier. Then inspect the response for each submitted shipment—not just the HTTP status—and save whether registration succeeded, failed, or remains uncertain. Registration starts the tracking workflow; it does not prove that the carrier has scanned the parcel or that tracking events are already available.

How to Register a Tracking Number via API Request Fields

This guide is for developers connecting an order management system, warehouse application, or ecommerce platform to a tracking API. It uses 17TRACK as a concrete integration example and explains which details must be checked against the documentation for your selected API version.

What registration does—and what it does not do

A registration request tells a tracking service which shipment you want it to track. It is different from purchasing a shipping label, booking a collection, or asking a carrier to create a shipment. In a typical integration, the shipping workflow produces a tracking number first, and your application registers that number afterward.

Keep these three events separate in your application:

  • Shipment created: your shipping system has assigned a tracking number.
  • Registration accepted: the tracking service has accepted the shipment for tracking.
  • Tracking information received: carrier events have become available through the tracking service.

Do not update an order to “in transit” simply because registration succeeded. A newly created label may not yet have a physical acceptance scan. Customer-facing shipment status should come from tracking events interpreted through your status-mapping rules, not from the registration response.

For 17TRACK integrations, start with the Tracking API overview and use the official API documentation as the authority for endpoints, field definitions, authentication, and response codes. The examples below focus on registration rather than the separate tasks of retrieving results or receiving updates.

Prepare the request fields before writing the API call

The most useful preparation is a small field contract between your shipping system and your tracking integration. Decide where each value originates, whether it can be missing, and how it will be validated.

Field or valuePurposeImplementation rule
Tracking numberIdentifies the shipment to track.Store and transmit it as a string; preserve leading zeros.
Carrier identifierIdentifies the carrier within the tracking provider’s system.Use the provider’s documented identifier, not an internal warehouse code.
Internal referenceConnects the registration to your shipment record.Use a supported reference field if available; retain your own database mapping regardless.
Additional identification dataMay help identify a shipment where a carrier requires more than its tracking number.Submit only fields documented for that integration and carrier.
API credentialAuthenticates the calling account.Keep it on the server and exclude it from application logs.

Treat the tracking number as an identifier

Never convert a tracking number into an integer. Numeric conversion can remove leading zeros, and large values may lose precision in some programming environments. Remove accidental surrounding whitespace, but do not strip punctuation or change letter case unless the relevant documentation or carrier format supports that normalization.

Validate obvious input errors before calling the API: empty strings, unexpected line breaks, and an order number copied into the tracking-number field. Avoid imposing one universal length or character rule across all carriers. A validation rule that fits one carrier may reject legitimate numbers from another.

Keep order references separate from shipment identities

An order can have multiple parcels, and a replacement shipment can introduce another tracking number. Model registration at the shipment or parcel level rather than assuming one tracking number per order.

If you use a provider-supported tag or reference field, prefer an opaque shipment reference rather than a customer’s email address or street address. Your own database should remain the authoritative connection between orders, shipments, tracking numbers, and carrier mappings.

Choose the right carrier code

A carrier code is not necessarily a universal industry identifier. The value recognized by a tracking platform may differ from the carrier name stored in your shipping software. Even two systems that use numeric codes can assign different numbers to the same carrier.

Maintain an explicit mapping from your shipping service to the tracking provider’s carrier identifier. Where necessary, distinguish a carrier’s regional operation or service from its broader brand. A mapping based only on a display name can become ambiguous when shipping systems use aliases.

  • When the carrier is known: use the documented carrier identifier when supported, particularly where tracking-number formats overlap.
  • When the carrier is unknown: use automatic detection only through the documented mechanism. Do not assume that omission, a blank string, zero, and null mean the same thing.
  • When the result looks wrong: verify the original label, the shipping service, and the mapping before repeatedly registering the same number.

Automatic detection is useful, but it is not evidence that a particular carrier physically holds the shipment. Similarly, a valid carrier code does not guarantee that the supplied tracking number belongs to that carrier.

Keep carrier mappings configurable rather than scattering them through application code. Record when a mapping was last checked and include a known shipment in regression tests whenever you change it.

Example: submit a 17TRACK registration request

The following example illustrates the 17TRACK v2.2 registration endpoint, the 17token authentication header, and an array containing one tracking-number object. Confirm that this version and its request requirements match your account and the official documentation before deployment. The tracking number is a placeholder and must be replaced with a real shipment identifier.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

This minimal example does not demonstrate carrier selection or carrier-specific supplementary fields. Check the registration documentation to determine how carrier detection works when the carrier field is omitted and whether your shipment needs additional information. If you supply a carrier, use the documented carrier field and the identifier expected by that API version.

Run this request from a server-side environment. Do not embed the token in a public storefront, browser script, or mobile application distributed to customers. An environment variable is convenient for a local example; production deployments should use your organization’s secret-management controls.

Before increasing volume, test one known shipment and inspect the complete response. Then test an invalid input and a batch containing both valid and invalid items. These checks reveal whether your integration actually handles item-level outcomes rather than merely recognizing an HTTP success response.

Read the response at three levels

A reliable response handler answers three separate questions: did the request reach the service, did the service accept the operation, and what happened to each shipment?

1. HTTP and transport outcome

A connection timeout, TLS failure, or interrupted response does not necessarily tell you whether the server processed the request. Mark that outcome as uncertain until you can reconcile it. An HTTP success status confirms a successful HTTP exchange, but you still need to inspect the application response.

2. Request-level outcome

Inspect the API’s documented top-level result and error fields. Authentication errors, malformed JSON, and account restrictions require different actions. Store the provider’s original error code and message rather than reducing every failure to “tracking unavailable.”

Do not assume that a numeric application code has the same meaning as an HTTP status code. Their meanings come from different layers and must be interpreted separately.

3. Shipment-level outcome

For batch registration, account for every submitted item. A response may distinguish accepted and rejected shipments; your parser should follow the exact schema documented for the selected version. Do not mark an entire batch as registered merely because one item succeeded.

Normalize provider responses into your own stable application states. For example, your database might use accepted, rejected, and uncertain. These are suggested internal states, not literal 17TRACK response values. Keep the original provider response available under an appropriate retention and access policy so developers can investigate discrepancies.

A useful registration record contains the internal shipment ID, submitted number, carrier selection, attempt time, API version, outcome, and provider error details. Keep registration status separate from delivery status.

Handle retries without creating an endless loop

Retry policy should depend on the failure, not simply on whether an exception occurred.

  • Invalid input: correct the field before retrying. Repeating an unchanged malformed request is unlikely to help.
  • Authentication failure: verify credentials and account configuration. Avoid repeatedly submitting the same failing batch.
  • Rate limiting: follow documented limits and any applicable retry instructions. Use bounded backoff rather than immediate parallel retries.
  • Temporary service failure: retry within a defined attempt and time budget.
  • Timeout after submission: reconcile the shipment’s registration state using documented API behavior before assuming the first attempt failed.
  • Duplicate-related response: check whether the shipment is already registered and correctly associated with your application record.

Do not assume registration is idempotent unless the documentation defines that behavior. Application-side deduplication reduces accidental repeated submissions, but it does not establish a provider’s duplicate-handling policy.

Use an internal uniqueness rule appropriate to your shipment model. Tracking number alone may not be a sufficient permanent key across carriers and long retention periods. Preserve carrier context and your own shipment identifier, and document how replacements and corrected numbers are handled.

Monitor registration separately from tracking updates

API monitoring should distinguish an integration failure from a shipment that simply has no new carrier event. These conditions require different owners and different fixes.

For registration, monitor acceptance and rejection counts, error categories, uncertain outcomes, retry backlog, and response latency. For subsequent tracking, monitor update receipt or retrieval failures separately. Avoid assigning numerical alert thresholds until you understand normal traffic and the provider’s documented operating limits.

A practical production check should answer:

  1. Does every shipment awaiting tracking have a registration record?
  2. Can every accepted registration be traced back to the correct parcel?
  3. Are rejected items routed to someone who can correct the underlying data?
  4. Are uncertain requests reconciled rather than abandoned or retried indefinitely?
  5. Are customer-facing statuses derived from shipment events rather than registration acceptance?
  6. Are credentials and unnecessary personal information excluded from logs?

For ecommerce operations, the operational handoff matters as much as the API call. Developers should own transport and parsing failures; shipping or fulfillment teams should be able to investigate incorrect labels, carrier mappings, and missing shipment information.

FAQ

Can I register a tracking number before the first carrier scan?

Registration and carrier scans are separate events. A service may accept a number before tracking events are available, subject to its validation rules. Do not interpret acceptance as proof that the carrier has received the parcel.

Do I always need to provide a carrier code?

That depends on the API’s documented detection behavior and the shipment involved. If the carrier is known, an explicit, correctly mapped identifier can reduce ambiguity. If it is unknown, use the documented automatic-detection method rather than inventing a carrier value.

Why did the API return HTTP success while a shipment failed?

The HTTP request can succeed while the application rejects an individual item. Read the top-level application result and the shipment-level results. This distinction is particularly important for batch requests.

What should I do when a registration request times out?

Treat the result as uncertain. The server may have processed the request before the connection failed. Check the provider’s documented duplicate behavior and available registration or tracking lookup methods, then reconcile or retry under a bounded policy.

Does registration automatically configure tracking notifications?

Do not assume that it does. Registration, tracking retrieval, and webhook configuration are separate integration concerns. Verify the relevant documentation and test the complete update path before relying on it for customer notifications.

Sources

  • 17TRACK API documentation — reference for registration endpoints, authentication, request fields, carrier identifiers, response schemas, and error handling. Match implementation details to the API version you deploy.
  • 17TRACK Tracking API overview — official starting point for the tracking API product and developer integration resources.