> ## Documentation Index > Fetch the complete documentation index at: https://docs.smartsend.io/llms.txt > Use this file to discover all available pages before exploring further. # Get tracking information > Returns current tracking status and complete event history for a shipment identified by its tracking number. Includes carrier information, destination details, and timestamped events. ## OpenAPI ````yaml /openapi-v2beta.json get /team/{team}/tracking/{trackingNumber} openapi: 3.1.0 info: title: Smart Send API description: >- Unified API for shipping operations including service points, routing, and rates. ## Localization The API performs language negotiation to determine the most suitable language for translatable content (such as service names, tracking descriptions, and error messages). The negotiation considers: 1. The `Accept-Language` request header (if provided) 2. The team's configured default language 3. English as the ultimate fallback The resolved language is used for all translatable strings in the response. ## Idempotency Write operations support **idempotency keys** so you can safely retry a request after a network error, timeout, or uncertain outcome without risking a duplicate side effect such as booking the same shipment twice. Idempotency is opt-in: include an `Idempotency-Key` header on a write request (`POST` or `DELETE`) to enable it. Requests sent without the header are not deduplicated. The key is a client-generated string of 16–128 characters (letters, digits, `.`, `_`, `-`) and is compared as-is, so it is case-sensitive. When a key is reused with an identical payload within 24 hours, the API returns the original response (status code and body) without re-executing the operation and sets the `Idempotency-Replayed: true` response header. Reusing a key with a different payload returns `422 Unprocessable Entity`. If the original request is still being processed, the retry returns `409 Conflict` with a `Retry-After` header indicating when to try again. Keys are scoped per client and expire automatically after the 24-hour window. See the [idempotency guide](https://docs.smartsend.io/api-reference/idempotency) for requirements and examples. ## User-Agent We recommend including a descriptive `User-Agent` header with every request, following the `Product/Version (Comments)` pattern from [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3). A good User-Agent helps us identify your integration and speeds up debugging when you contact support. Example: `smart-send-logistics/8.1.0 (WooCommerce/8.5.0; WordPress/6.4.2; PHP/8.1)` ## Request-ID We recommend including a unique `Request-ID` header with every request. The value is echoed back in the response and included in internal logs, making it possible to correlate logs from your implementation with logs in Smart Send. This is especially useful when contacting support about a specific request. version: 2.0.0-beta contact: name: Smart Send url: https://www.smartsend.io servers: - url: https://app.smartsend.io/api/v2 description: Production security: - bearerAuth: [] - oauth2: [] tags: - name: Teams description: Teams available to the authenticated user - name: Service Points description: Pickup points and delivery locations - name: Routing description: Reference data (carriers, services, addons) and route availability - name: Rates description: Shipping rates and pricing for specific shipments - name: Tracking description: Shipment tracking information and event history - name: Shipments description: Create and manage shipments - name: Booking description: Booking of shipments externalDocs: description: Booking documentation url: https://docs.smartsend.io/features/booking - name: Booking batches description: |- Batch operations for booking multiple shipments asynchronously. Processing operates after the _first-in-first-out_ principle. externalDocs: description: Batch booking documentation url: https://docs.smartsend.io/features/booking#batch-booking paths: /team/{team}/tracking/{trackingNumber}: get: tags: - Tracking summary: Get tracking information description: >- Returns current tracking status and complete event history for a shipment identified by its tracking number. Includes carrier information, destination details, and timestamped events. operationId: getTracking parameters: - $ref: '#/components/parameters/team' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Request-ID' - name: trackingNumber in: path required: true schema: type: string minLength: 1 maxLength: 255 examples: - TRK123456789 description: The tracking number/code assigned to the shipment by the carrier responses: '200': description: Tracking information retrieved successfully headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Tracking' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerAuth: [] - oauth2: - tracking:read components: parameters: team: name: team in: path required: true schema: type: string minLength: 1 examples: - ad9546c1-393e-49a5-9a72-5cc146c9bec5 description: Team identifier. All resources are scoped to this team. Accept-Language: name: Accept-Language in: header required: false schema: type: string default: en examples: - da-DK, da;q=0.9, en;q=0.8 description: >- Preferred language(s) for translatable content using BCP 47 language tags. Supports quality values (q-factors) for priority ordering. The API negotiates the best available language based on this header, the team's configured language, and available translations. If omitted, the team's default language is used. Request-ID: name: Request-ID in: header required: false schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._-]{1,128}$ description: >- Any value passed in this request will be returned in the same header. This can be used to correlate requests between client and server. examples: uuid: summary: UUID v4 value: 3f5d9a8e-8e6f-4d9b-9d9c-9c6b3db2d1a0 opaque: summary: Opaque client-generated key value: booking-12345-at-1768609378 headers: Correlation-ID: description: >- Unique identifier for the request, useful for debugging and support. The id is automatically assigned to each request and can helps trace the request in system logs. Provide this value in case of any errors helps debugging. schema: type: string format: uuid examples: - 550e8400-e29b-41d4-a716-446655440000 Request-ID: description: >- If the request contained a `Request-ID` then the same value is returned as the `Request-ID`. This can be used to correlate requests between client and server. schema: type: string Retry-After: description: Number of seconds to wait before retrying the request. schema: type: integer examples: - 30 schemas: Tracking: type: object required: - uuid - tracking_number - tracking_url - state - description - locale - last_synced_at - last_updated_at - estimated_delivery - delivered_at - returned_at - service - receiver - destination - events properties: uuid: type: string format: uuid description: Unique identifier for this tracking record examples: - 8c0a32d1-7f32-4e4e-9876-0f1234567890 tracking_number: type: string description: The tracking number/code assigned by the carrier examples: - TRK123456789 tracking_url: type: - 'null' - string format: uri description: Public URL for tracking this shipment examples: - https://track.smartsend.io/8c0a32d1 state: $ref: '#/components/schemas/TrackingState' description: type: - 'null' - string description: Localized description of the current tracking state locale: type: - 'null' - string description: BCP 47 language tag indicating the locale used for descriptions examples: - da-DK last_synced_at: type: - 'null' - string format: date-time description: When tracking data was last fetched from the carrier last_updated_at: type: - 'null' - string format: date-time description: Timestamp of the most recent tracking event estimated_delivery: anyOf: - type: 'null' - $ref: '#/components/schemas/DateTimeRange' delivered_at: type: - 'null' - string format: date-time description: When the shipment was delivered (if applicable) returned_at: type: - 'null' - string format: date-time description: When the shipment was returned to sender (if applicable) service: $ref: '#/components/schemas/Service' description: The shipping service used for this shipment receiver: anyOf: - type: 'null' - $ref: '#/components/schemas/TrackingReceiver' destination: anyOf: - type: 'null' - $ref: '#/components/schemas/TrackingDestination' events: type: array description: >- List of tracking events in reverse chronological order (most recent first) items: $ref: '#/components/schemas/TrackingEvent' TrackingState: type: string description: Current high-level state of the shipment enum: - Pending - InfoReceived - InTransit - OutForDelivery - DeliveryFailure - Delivered - AvailableForPickup - Returning - Returned - Unknown - Exception - Expired examples: - InTransit DateTimeRange: type: object description: A date-time range with start and end timestamps properties: start: type: - 'null' - string format: date-time description: Start of the range (ISO 8601 datetime) end: type: - 'null' - string format: date-time description: End of the range (ISO 8601 datetime) required: - start - end Service: type: object description: >- Base shipping service definition with carrier information and routing flags (no addons). required: - service_code - service_name - carrier_code - carrier_name - carrier_logo_url - carrier_icon_url - is_pickup - is_return properties: service_code: type: string description: Full service code (carrier_code + '_' + carrier-specific code) examples: - postnord_agent service_name: type: string description: Localized human-readable service name examples: - Pickup Point carrier_code: type: string description: Unique carrier code examples: - postnord carrier_name: type: string description: Human-readable carrier name examples: - PostNord carrier_logo_url: type: string format: uri description: URL to the carrier's logo image carrier_icon_url: type: string format: uri description: URL to the carrier's icon image is_pickup: type: boolean description: Whether this service delivers to pickup points is_return: type: boolean description: Whether this is a return service TrackingReceiver: type: object description: Recipient information for the shipment properties: name: type: - 'null' - string description: Recipient's name company: type: - 'null' - string description: Company or organization name email: type: - 'null' - string format: email description: Recipient's email address phone: type: - 'null' - string description: Recipient's phone number required: - name - company - email - phone TrackingDestination: type: object required: - type - address - country - coordinates - pickup_point description: Delivery destination for the shipment properties: type: type: string enum: - HOME_ADDRESS - PICKUP_POINT - LOCKER - BUSINESS_ADDRESS description: Type of delivery destination address: anyOf: - type: 'null' - $ref: '#/components/schemas/Address' country: type: string minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code coordinates: anyOf: - type: 'null' - $ref: '#/components/schemas/Location' pickup_point: anyOf: - type: 'null' - $ref: '#/components/schemas/TrackingPickupPoint' TrackingEvent: type: object required: - uuid - category - status_code - description - happened_at - recorded_at - location - coordinates - note properties: uuid: type: string format: uuid description: Unique identifier for this tracking event category: $ref: '#/components/schemas/TrackingEventCategory' status_code: $ref: '#/components/schemas/TrackingEventType' description: type: string description: Localized description of the event happened_at: type: string format: date-time description: When the event actually occurred recorded_at: type: string format: date-time description: When the event was recorded in the system location: $ref: '#/components/schemas/EventLocation' coordinates: anyOf: - type: 'null' - $ref: '#/components/schemas/Location' note: type: - 'null' - string description: Additional note or details from the carrier ErrorResponse: type: object required: - message properties: message: type: string description: Human-readable error message examples: - Something unexpected happened. ValidationErrorResponse: type: object required: - message - errors properties: message: type: string description: Human-readable error message summarizing the validation failure errors: type: object additionalProperties: type: array items: type: string description: >- Object containing field names as keys and arrays of error messages as values examples: - message: The given data was invalid. errors: field_name: - The field name is required. RateLimitErrorResponse: type: object required: - message properties: message: type: string description: Human-readable error message indicating rate limit exceeded Address: type: object required: - address_lines - postal_code - city - country - administrative_area properties: address_lines: type: - 'null' - array items: type: string maxItems: 3 description: Street address lines (e.g., street name, building, floor) examples: - - 3200 Whitehaven St. NW - Building A, Floor 2 postal_code: type: - 'null' - string description: Postal/ZIP code examples: - '20008' city: type: string description: City examples: - Washington country: type: string minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code examples: - US administrative_area: type: - 'null' - string minLength: 2 maxLength: 3 description: >- The sub-national subdivision code (e.g., state, province, or department) representing the suffix part of the ISO 3166-2 standard. This field should contain only the characters following the hyphen. For example, for 'US-NY', provide 'NY'; for 'JP-13', provide '13' examples: - DC Location: type: object required: - latitude - longitude properties: latitude: type: number description: Latitude coordinate (WGS 84) examples: - 55.689748 longitude: type: number description: Longitude coordinate (WGS 84) examples: - 12.553726 TrackingPickupPoint: type: object description: Pickup point details when destination type is PICKUP_POINT or LOCKER properties: id: type: - 'null' - string description: Carrier's unique identifier for this pickup point name: type: - 'null' - string description: Name of the pickup point type: anyOf: - type: 'null' - $ref: '#/components/schemas/ServicePointType' required: - id - name - type TrackingEventCategory: type: string description: Category grouping for tracking events enum: - AvailableForPickup - Change - Delayed - Delivered - DeliveryFailure - Error - Exception - Expired - External - Info - InTransit - Notification - OutForDelivery - System TrackingEventType: type: string description: Specific tracking event type code following the format Category_Subtype enum: - Error_NotFound - Error_Other - Expired_Other - Internal_Printed - Internal_Packed - Internal_QualityCheck - Internal_Scan - Internal_Other - Info_Received - Info_Other - Notification_Registered - Notification_Update - Notification_Delivered - Notification_ActionRequired - Notification_InformationRequired - Notification_Other - InTransit_PickedUp - InTransit_Arrival - InTransit_Departure - InTransit_Other - OutForDelivery_Other - DeliveryFailure_NoBody - DeliveryFailure_Security - DeliveryFailure_Rejected - DeliveryFailure_InvalidAddress - DeliveryFailure_AddressCorrectable - DeliveryFailure_NoReceiver - DeliveryFailure_WillRetry - DeliveryFailure_ActionRequired - DeliveryFailure_Other - AvailableForPickup_Other - Delivered_FrontDoor - Delivered_Neighbor - Delivered_MailRoom - Delivered_POBox - Delivered_SafeLocation - Delivered_Locker - Delivered_Other - Delayed_Weather - Delayed_Operational - Delayed_Clearance - Delayed_CustomsHeld - Delayed_Other - Info_CustomsChargesDue - Info_CustomsChargesPaid - Info_CustomsCleared - Info_CustomsOther - Exception_Returning - Exception_Returned - Exception_ReturnedAsRequested - Exception_ReturnedDamaged - Exception_ReturnedNotAvailable - Exception_ReturnedInvalidAddress - Exception_NoBody - Exception_Security - Exception_Damage - Exception_Rejected - Exception_Stopped - Exception_Lost - Exception_Destroyed - Exception_Cancel - Exception_Other - System_Identification - System_Unknown - System_Other - Change_AddressUpdated - Change_RecipientUpdated - Change_ServicePointUpdated - Change_DeliveryOptionsUpdated - Change_RetentionExtended - Change_Rerouted - Change_Other EventLocation: type: object description: Location where the tracking event occurred required: - city - postal_code - country - administrative_area properties: city: type: - 'null' - string description: City where the event occurred postal_code: type: - 'null' - string description: Postal code where the event occurred country: type: string minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code examples: - US administrative_area: type: - 'null' - string minLength: 2 maxLength: 3 description: >- The sub-national subdivision code (e.g., state, province, or department) representing the suffix part of the ISO 3166-2 standard. This field should contain only the characters following the hyphen. For example, for 'US-NY', provide 'NY'; for 'JP-13', provide '13' examples: - NY ServicePointType: type: string enum: - post_office - relay_point - parcel_store - self_service_locker - other - unknown description: Type of service point responses: Unauthorized: description: Authentication credentials were missing or invalid headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: The authenticated user does not have permission to perform this action headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: The requested resource was not found headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: The request data failed validation headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' TooManyRequests: description: Rate limit exceeded. Wait before retrying. headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' InternalServerError: description: An unexpected error occurred on the server headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServiceUnavailable: description: The service is temporarily unavailable. Please try again later. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer oauth2: type: oauth2 description: OAuth 2.0 Authorization Code flow for API access flows: authorizationCode: authorizationUrl: https://app.smartsend.io/oauth/authorize tokenUrl: https://app.smartsend.io/oauth/token scopes: service_points: Access service points and pickup locations routing: Access routing information (carriers, services, addons, routes) tracking:read: Access shipment tracking information rates:read: Get shipping rates and pricing shipment:read: Read shipment information shipment:write: Create and manage shipments ````