openapi: 3.0.3
info:
  title: Shippit Book Tracking API
  description: 'The Shippit API (v3) is the REST interface to Shippit''s Australian multi-carrier shipping and fulfillment platform. Merchants use it to request live carrier quotes, create and cancel orders, book consignments with carriers, retrieve shipping labels and pick slips, and track parcels via pull requests or push webhooks.


    Base URLs are `https://app.shippit.com/api/3` (production) and `https://app.staging.shippit.com/api/3` (staging sandbox). Every request is authenticated with a per-merchant API key passed as an HTTP Bearer token in the `Authorization` header.


    NOTE ON FIDELITY: The base URLs, Bearer authentication, and the pull-based tracking path (`GET /orders/{tracking_number}/tracking`) are grounded in Shippit''s published developer documentation. The remaining request and response schemas below are MODELED from Shippit''s endpoint descriptions and order-flow guide, not copied field-for-field from an official machine-readable spec. Treat property-level detail as illustrative and reconcile against the live Developer Centre before generating client code.'
  version: '3'
  contact:
    name: Shippit Developer Centre
    url: https://developer.shippit.com/
  x-fidelity: Base URLs, Bearer auth, and the tracking path are confirmed from docs; other request/response schemas are modeled and should be reconciled.
servers:
- url: https://app.shippit.com/api/3
  description: Production
- url: https://app.staging.shippit.com/api/3
  description: Staging (sandbox)
security:
- bearerAuth: []
tags:
- name: Tracking
  description: Pull-based order tracking.
paths:
  /orders/{tracking_number}/tracking:
    parameters:
    - $ref: '#/components/parameters/TrackingNumber'
    get:
      operationId: getOrderTracking
      tags:
      - Tracking
      summary: Track an order (pull)
      description: Pull-based tracking. Returns the current status and tracking history for an order by its tracking number. Path grounded in Shippit tracking docs; response fields MODELED.
      responses:
        '200':
          description: The tracking status and history for the order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    TrackingNumber:
      name: tracking_number
      in: path
      required: true
      description: The Shippit tracking number identifying the order.
      schema:
        type: string
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    TrackingResponse:
      type: object
      description: MODELED tracking response.
      properties:
        response:
          type: object
          properties:
            tracking_number:
              type: string
            state:
              type: string
            tracking:
              type: array
              items:
                type: object
                properties:
                  status:
                    type: string
                  status_message:
                    type: string
                  latitude:
                    type: number
                  longitude:
                    type: number
                  updated_at:
                    type: string
                    format: date-time
  responses:
    Unauthorized:
      description: Missing or invalid Bearer API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Per-merchant API key (referred to as the API Secret) passed as `Authorization: Bearer YOUR_API_KEY`. Obtain the key from the Shippit merchant dashboard; use a staging key against the staging base URL.'