openapi: 3.1.0
info:
  title: TrackingMore 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
  - name: Couriers
    description: List available couriers and detect carrier from tracking number
  - name: Air Waybills
    description: Track air cargo using Master Air Waybill (MAWB) numbers
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'
  /couriers/all:
    get:
      operationId: getAllCouriers
      summary: Get all couriers
      description: >-
        Retrieve the full list of supported carriers/couriers available on the
        TrackingMore platform (1,300+ globally).
      tags:
        - Couriers
      responses:
        '200':
          description: List of all supported couriers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CourierListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /couriers/detect:
    post:
      operationId: detectCourier
      summary: Detect courier
      description: >-
        Automatically detect which carrier(s) a tracking number belongs to
        based on pattern matching and heuristics.
      tags:
        - Couriers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetectCourierRequest'
            examples:
              detect:
                summary: Detect courier for a tracking number
                value:
                  tracking_number: "9400111899223397576146"
      responses:
        '200':
          description: Detected courier(s) for the tracking number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectCourierResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /awb:
    post:
      operationId: createAirWaybill
      summary: Track air waybill
      description: >-
        Track an air cargo shipment using a Master Air Waybill (MAWB) number
        in format XXX-XXXXXXXX. Each air waybill track consumes 50 credits.
      tags:
        - Air Waybills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AirWaybillRequest'
            examples:
              awb:
                summary: Track an air waybill
                value:
                  awb_number: "020-12345678"
      responses:
        '200':
          description: Air waybill tracking result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirWaybillResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  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.
  schemas:
    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
    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
    DetectCourierRequest:
      type: object
      required:
        - tracking_number
      properties:
        tracking_number:
          type: string
          description: The tracking number to detect the carrier for
          example: "9400111899223397576146"
    AirWaybillRequest:
      type: object
      required:
        - awb_number
      properties:
        awb_number:
          type: string
          description: Master Air Waybill number in format XXX-XXXXXXXX or XXXXXXXXXXX
          pattern: '^\d{3}[ -]?(\d{8})$'
          example: "020-12345678"
    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
    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
    Courier:
      type: object
      properties:
        courier_code:
          type: string
          description: Unique carrier code used in API requests
          example: "usps"
        courier_name:
          type: string
          description: Human-readable carrier name
          example: "USPS"
        courier_url:
          type: string
          format: uri
          description: Carrier website URL
        phone:
          type: string
          description: Carrier customer service phone number
        country:
          type: string
          description: Country where this carrier primarily operates
        type:
          type: string
          description: Carrier type (e.g., express, postal, freight)
    AirWaybill:
      type: object
      properties:
        awb_number:
          type: string
          description: Master Air Waybill number
        airline:
          type: string
          description: Airline name
        origin:
          type: string
          description: Origin airport IATA code
        destination:
          type: string
          description: Destination airport IATA code
        status:
          type: string
          description: Shipment status
        events:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date-time
              location:
                type: string
              description:
                type: string
    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)
    TrackingResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/Tracking'
    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
    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'
    CourierListResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Courier'
    DetectCourierResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Courier'
    AirWaybillResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/AirWaybill'
    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
  responses:
    BadRequest:
      description: Bad request - missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 4000
            message: "Bad Request"
            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: []
    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: []