TrackingMore Trackings API

openapi: 3.1.0
info:
  title: TrackingMore Air Waybills Trackings API
  description: TrackingMore provides a unified multi-carrier shipment tracking REST API supporting 1,300+ carriers globally. The API enables real-time parcel tracking, webhook notifications for shipment status changes, automated carrier detection, delivery analytics, and branded tracking page customization. Designed for D2C merchants, logistics platforms, and ecommerce integrations across Shopify, Amazon, eBay, WooCommerce, and Magento.
  version: v4
  contact:
    url: https://support.trackingmore.com/
  termsOfService: https://www.trackingmore.com/terms-of-service.html
  license:
    name: Proprietary
    url: https://www.trackingmore.com/terms-of-service.html
servers:
- url: https://api.trackingmore.com/v4
  description: TrackingMore API v4 (production)
security:
- ApiKeyAuth: []
tags:
- name: Trackings
  description: Create, retrieve, update, and delete shipment trackings
paths:
  /trackings/create:
    post:
      operationId: createTracking
      summary: Create a tracking
      description: Create a new shipment tracking. Requires a tracking number and courier code. Each unique tracking_number + courier_code pair consumes 1 credit.
      tags:
      - Trackings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTrackingRequest'
            examples:
              basic:
                summary: Basic tracking creation
                value:
                  tracking_number: '9400111899223397576146'
                  courier_code: usps
      responses:
        '200':
          description: Tracking created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /trackings/batch:
    post:
      operationId: batchCreateTrackings
      summary: Batch create trackings
      description: Create up to 40 shipment trackings in a single API call. Each item requires a tracking_number and courier_code.
      tags:
      - Trackings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateTrackingRequest'
              maxItems: 40
            examples:
              batch:
                summary: Batch of two trackings
                value:
                - tracking_number: '9400111899223397576146'
                  courier_code: usps
                - tracking_number: 1Z999AA10123456784
                  courier_code: ups
      responses:
        '200':
          description: Batch tracking creation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchTrackingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /trackings/get:
    get:
      operationId: getTrackingResults
      summary: Get tracking results
      description: Retrieve tracking results for one or more shipments. Supports filtering by courier code, tracking status, date range, and other parameters.
      tags:
      - Trackings
      parameters:
      - name: tracking_number
        in: query
        description: Tracking number to filter by
        schema:
          type: string
      - name: courier_code
        in: query
        description: Carrier/courier code to filter by
        schema:
          type: string
      - name: status
        in: query
        description: Shipment status to filter by (e.g., pending, transit, delivered, exception)
        schema:
          type: string
          enum:
          - pending
          - transit
          - delivered
          - exception
          - expired
          - notfound
          - undelivered
          - pickup
          - inforeceived
      - name: created_at_min
        in: query
        description: Filter by minimum creation date (Unix timestamp or ISO 8601)
        schema:
          type: string
      - name: created_at_max
        in: query
        description: Filter by maximum creation date (Unix timestamp or ISO 8601)
        schema:
          type: string
      - name: updated_at_min
        in: query
        description: Filter by minimum last updated date (Unix timestamp or ISO 8601)
        schema:
          type: string
      - name: updated_at_max
        in: query
        description: Filter by maximum last updated date (Unix timestamp or ISO 8601)
        schema:
          type: string
      - name: page
        in: query
        description: Page number for pagination (default 1)
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Number of results per page (default 40, max 100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 40
      - name: lang
        in: query
        description: Language code for translated tracking messages
        schema:
          type: string
      responses:
        '200':
          description: List of tracking results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /trackings/update/{id}:
    put:
      operationId: updateTrackingById
      summary: Update a tracking
      description: Update metadata or custom fields for an existing tracking identified by its unique ID.
      tags:
      - Trackings
      parameters:
      - name: id
        in: path
        required: true
        description: Unique tracking identifier
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTrackingRequest'
      responses:
        '200':
          description: Tracking updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /trackings/delete/{id}:
    delete:
      operationId: deleteTrackingById
      summary: Delete a tracking
      description: Permanently delete a shipment tracking by its unique ID.
      tags:
      - Trackings
      parameters:
      - name: id
        in: path
        required: true
        description: Unique tracking identifier
        schema:
          type: string
      responses:
        '200':
          description: Tracking deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /trackings/retrack/{id}:
    post:
      operationId: retrackTrackingById
      summary: Retrack a tracking
      description: Request a fresh tracking update for a shipment that has stopped updating. Useful for expired or stale trackings.
      tags:
      - Trackings
      parameters:
      - name: id
        in: path
        required: true
        description: Unique tracking identifier
        schema:
          type: string
      responses:
        '200':
          description: Retrack request submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  schemas:
    UpdateTrackingRequest:
      type: object
      properties:
        title:
          type: string
          description: Updated title/label for the tracking
        customer_name:
          type: string
          description: Updated customer name
        customer_email:
          type: string
          format: email
          description: Updated customer email
        order_id:
          type: string
          description: Updated internal order ID
        note:
          type: string
          description: Updated note or comment
        language:
          type: string
          description: Updated language code for translated messages
    Tracking:
      type: object
      properties:
        id:
          type: string
          description: Unique tracking identifier
        tracking_number:
          type: string
          description: Shipment tracking number
        courier_code:
          type: string
          description: Carrier/courier code
        order_id:
          type: string
          description: Associated order ID
        title:
          type: string
          description: Custom title/label for the tracking
        customer_name:
          type: string
          description: Customer name
        customer_email:
          type: string
          description: Customer email
        note:
          type: string
          description: Custom note
        status:
          type: string
          description: Current tracking status
          enum:
          - pending
          - inforeceived
          - transit
          - pickup
          - delivered
          - undelivered
          - exception
          - expired
          - notfound
        substatus:
          type: string
          description: More specific sub-status code
        origin_country:
          type: string
          description: ISO country code of origin
        destination_country:
          type: string
          description: ISO country code of destination
        created_at:
          type: string
          format: date-time
          description: Timestamp when this tracking was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp of last update
        last_event:
          type: string
          description: Description of the most recent tracking event
        last_update_time:
          type: string
          format: date-time
          description: Time of the most recent carrier update
        origin_info:
          type: object
          description: Tracking events at the origin location
          properties:
            trackinfo:
              type: array
              items:
                $ref: '#/components/schemas/TrackingEvent'
        destination_info:
          type: object
          description: Tracking events at the destination location
          properties:
            trackinfo:
              type: array
              items:
                $ref: '#/components/schemas/TrackingEvent'
        tracking:
          type: object
          description: Combined tracking events object
    TrackingListResponse:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      - type: object
        properties:
          data:
            type: object
            properties:
              total:
                type: integer
                description: Total number of trackings matching the query
              trackings:
                type: array
                items:
                  $ref: '#/components/schemas/Tracking'
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        message:
          type: string
          description: Human-readable error message
        data:
          type: array
          items: {}
          description: Empty array for error responses
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: Response code (200 = success)
        message:
          type: string
          description: Human-readable response message
        data:
          description: Response payload (varies by endpoint)
    BatchTrackingResponse:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      - type: object
        properties:
          data:
            type: object
            properties:
              accepted:
                type: array
                items:
                  $ref: '#/components/schemas/Tracking'
              rejected:
                type: array
                items:
                  type: object
                  properties:
                    tracking_number:
                      type: string
                    courier_code:
                      type: string
                    error:
                      type: string
    CreateTrackingRequest:
      type: object
      required:
      - tracking_number
      - courier_code
      properties:
        tracking_number:
          type: string
          description: The shipment tracking number
          example: '9400111899223397576146'
        courier_code:
          type: string
          description: The carrier/courier code (e.g., usps, ups, fedex, dhl)
          example: usps
        title:
          type: string
          description: Custom title or label for this tracking
        customer_name:
          type: string
          description: Name of the customer associated with this shipment
        customer_email:
          type: string
          format: email
          description: Customer email for notifications
        order_id:
          type: string
          description: Your internal order ID
        order_id_url:
          type: string
          format: uri
          description: URL to your order management page for this order
        note:
          type: string
          description: Free-form note or comment about this tracking
        language:
          type: string
          description: Language code for translated tracking messages (e.g., en, zh-CN)
        destination_country:
          type: string
          description: ISO 3166-1 alpha-2 destination country code
        origin_country:
          type: string
          description: ISO 3166-1 alpha-2 origin country code
    TrackingEvent:
      type: object
      properties:
        checkpoint_date:
          type: string
          format: date-time
          description: Date and time of this tracking checkpoint
        location:
          type: string
          description: Location description for this checkpoint
        checkpoint_status:
          type: string
          description: Status at this checkpoint
        substatus:
          type: string
          description: Detailed sub-status at this checkpoint
        details:
          type: string
          description: Human-readable description of the checkpoint event
    TrackingResponse:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Tracking'
  responses:
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 4004
            message: Not found.
            data: []
    RateLimitExceeded:
      description: Rate limit exceeded. Wait 120 seconds before retrying. Pro plan limit is 10 req/s (3 req/s for create tracking).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 4029
            message: Too many requests.
            data: []
    Unauthorized:
      description: Authentication failed - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 4001
            message: Invalid API key.
            data: []
    BadRequest:
      description: Bad request - missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 4000
            message: Bad Request
            data: []
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Tracking-Api-Key
      description: API key for authentication. Obtainable from your TrackingMore account dashboard. Up to 4 API keys per account.