> ## Documentation Index
> Fetch the complete documentation index at: https://developer.firstbasedev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up shipment details by tracking numbers

> Returns shipment details for the provided tracking numbers, paginated. At least one tracking number must be supplied. Each result includes carrier, tracking status, and the order items associated with the shipment.



## OpenAPI

````yaml /openapi.json get /api/v1/shipments
openapi: 3.1.0
info:
  title: Firstbase API Specification Beta
  description: Integration endpoints for Firstbase
  version: 0.1.0
servers:
  - url: /
    description: Default
security:
  - ApiKey: []
tags:
  - name: Inventory Orders
    description: Create and manage inventory orders
  - name: Shipment Notices V1
    description: 'Query shipment notice orders (V1: package items expose `inventories` list)'
  - name: Packages
    description: ''
  - name: Categories
    description: Query available categories for asset creation
  - name: Catalog
    description: ''
  - name: New Joiners
    description: New joiner provisioning pipeline for the organization
  - name: Orders
    description: ''
  - name: People
    description: >-
      Manage the users of Firstbase for your organization. API follows the SCIM
      standard.
    externalDocs:
      url: https://scim.cloud/
  - name: People — Lifecycle
    description: Offboard and reactivate users.
  - name: Assets
    description: Manage inventory assets
  - name: Regions V1
    description: Query regions (V1)
  - name: Warehouses V1
    description: Query warehouses (V1)
  - name: Brands
    description: Query available brands for asset creation
  - name: Inventory
    description: ''
  - name: Replacements
    description: Create and manage equipment replacements
  - name: Offices
    description: Manage and query office locations for the authenticated organization
  - name: Returns
    description: Return and Replacements
paths:
  /api/v1/shipments:
    get:
      tags:
        - Shipment
      summary: Look up shipment details by tracking numbers
      description: >-
        Returns shipment details for the provided tracking numbers, paginated.
        At least one tracking number must be supplied. Each result includes
        carrier, tracking status, and the order items associated with the
        shipment.
      operationId: listShipments
      parameters:
        - name: trackingNumbers
          in: query
          description: One or more carrier tracking numbers to look up (required)
          required: true
          schema:
            type: array
            items:
              type: string
          example: 1Z999AA10123456784
        - name: page
          in: query
          description: 'Page number to return (1-based, default: 1)'
          required: false
          allowEmptyValue: true
          schema:
            type: integer
            format: int32
            default: 1
          example: 1
        - name: size
          in: query
          description: 'Number of results per page (default: 10)'
          required: false
          allowEmptyValue: true
          schema:
            type: integer
            format: int32
            default: 10
          example: 10
      responses:
        '200':
          description: >-
            Paginated list of shipment details matching the provided tracking
            numbers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaginatedShipmentDetailsDto'
        '400':
          description: Bad request — missing or invalid trackingNumbers parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
components:
  schemas:
    PaginatedShipmentDetailsDto:
      type: object
      properties:
        size:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        pageNumber:
          type: integer
          format: int32
        data:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentOrderItemDto'
      required:
        - data
        - pageNumber
        - size
        - totalElements
        - totalPages
    PublicApiHttpErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiError'
      required:
        - errors
    ShipmentOrderItemDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Shipment ID
          example: 123E4567-E89B-12D3-A456-426614174000
        trackingCode:
          type: string
          description: Tracking code
          example: 1Z00000000
        carrier:
          type: string
          description: The carrier name
          example: UPS
        status:
          type: string
          description: The current status of the shipment
          example: DELIVERED
        trackingHistory:
          type: array
          description: >-
            A history of recorded shipment status updates in order of date
            received
          items:
            $ref: '#/components/schemas/ShipmentStatusDTO'
        createdAt:
          type: string
          format: date-time
          description: Timestamp at which the record was created
        orderItemIds:
          type: array
          description: A list of associated Order item IDs
          examples:
            - 123E4567-E89B-12D3-A456-426614174000
            - 123E4567-E89B-12D3-A456-426614175000
          items:
            type: string
            format: uuid
        trackingUrl:
          type: string
          description: Tracking link
          example: http://trackinglink.com/trackingcode
      required:
        - carrier
        - createdAt
        - id
        - status
        - trackingCode
        - trackingHistory
    PublicApiError:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable description of the error
          example: Invalid request
        source:
          type: string
          description: >-
            Entity or field path that caused the error (for example order,
            shipmentNotice, or person:email)
          example: request
      required:
        - detail
        - source
    ShipmentStatusDTO:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Internal id of the tracker status
          example: 123E4567-E89B-12D3-A456-426614174000
        status:
          type: string
          description: The status of the shipment
          example: IN_TRANSIT
        createdAt:
          type: string
          format: date-time
          description: Timestamp at which the event was received
      required:
        - createdAt
        - id
        - status
  securitySchemes:
    ApiKey:
      type: apiKey
      description: Prefix the value with "ApiKey" to indicate the custom authorization type
      name: Authorization
      in: header

````