Schemas

{
  id: string  // Use as `connectorId` in rate and booking requests
  carrier: TNT_AU | BEX_AU
  name: string  // Human-readable label for this connector
  services: {
    serviceCode: string
    description: string
  }[]  // Available services for this connector. Populated after the first successful connection test. Carriers with a static catalog (BEX AU) always return services; dynamic carriers (TNT AU) return an empty array until tested.
}

{
  connectors: ConnectorSummary[]
}

{
  suburb: string
  postcode: string
  state: string
  residential: boolean  // Whether this is a residential address. Triggers a residential surcharge on collection (RSP) or delivery (RSD) where applicable.
}

{
  companyName: string
  contactName?: string
  phoneAreaCode?: string
  phoneNumber?: string
  address1: string
  address2?: string
  suburb: string
  state: string
  postcode: string
  email?: string  // Receiver email address for carrier delivery notifications (BEX AU)
}

{
  count: integer
  lengthCm: number
  widthCm: number
  heightCm: number
  weightKg: number
}

{
  from: Address
  to: Address
  packages: Package[]
  dangerousGoods: boolean
  date?: string  // Shipping date (YYYY-MM-DD). Defaults to today in AEST if omitted.
  localDateTime?: string  // Current local time in AEST (yyyy-MM-ddTHH:mm:ss, no TZ suffix). Used by TNT to determine booking cutoff eligibility. Defaults to current AEST time if omitted.
  serviceCode?: string | null  // If set, returns pricing for this service only. Omit (or pass null) to receive all available services.
  isDocument?: boolean  // Mark as a document shipment (TNT AU — affects packaging type and commodity code)
}

{
  serviceCode: string
  description: string
  price: number
  currency: string
  eta?: string | null  // Estimated delivery datetime (ISO 8601, no TZ suffix)
  transitDays?: integer | null  // Transit duration in whole days, for carriers (e.g. TGE AU) whose rate response gives a duration rather than a delivery date. Null when `eta` is supplied directly instead.
  bookingCutoff: string  // Latest time to book for this service today (HH:mm:ss)
  collectionCutoff: string  // Latest time for courier collection today (HH:mm:ss)
  priceGst?: number  // GST component of the price (BEX AU only)
  priceIncGst?: number  // Total price including GST (BEX AU only)
}

{
  connectorId: string
  carrier: string
  success: boolean
  rates?: RatedService[]  // Present when success is true
  error?: CarrierError  // Present when success is false
}

{
  results: AggregatedRateResult[]
}

{
  count: integer
  totalWeightKg: number
  maxLengthCm: number
  maxWidthCm: number
  maxHeightCm: number
}

{
  sender: BookingAddress
  collection: BookingAddress  // Collection address — often the same as sender but can differ (e.g. a warehouse pickup for an office-based account).
  receiver: BookingAddress
  items: Items
  packagingCode: CT | BX | SA | PA | EN | CR | DR | RO | BG | PC  // TNT AU packaging codes: `CT` — Carton, `BX` — Box, `SA` — Satchel, `PA` — Pallet, `EN` — Envelope
  serviceCode: string  // Carrier service code from a prior `getRates` call
  collectionDateTime: string  // Pickup ready time in AEST local time, no TZ suffix. Must be 07:00–17:00 AEST, ≥ 120 minutes before collectionCloseTime.
  collectionCloseTime: string  // Premises close time in AEST local time as hhmm string. Must be 13:00–19:00 AEST.
  payer: Sender | Receiver | ThirdParty
  payerAccountNumber?: string  // Account number to charge when `payer` is `Receiver` or `ThirdParty`. Not required when `payer` is `Sender` (the connector's own account is charged).
  thirdPartyAddress?: BookingAddress  // Required when `payer` is `ThirdParty` (TNT AU). The third-party account holder's address.
  dangerousGoods: boolean
  dangerousGoodsDetails?: {
    unNumber: string  // UN number (4 digits)
    packingGroup?: I | II | III  // Packing group (if applicable)
    hazClass: string  // Hazard class (e.g. `3`, `8`)
    packageType: string  // Package type description
    quantity: integer
    aggregateQuantity: integer
    shippingName: string  // Proper shipping name
    subRisk?: string  // Subsidiary risk (optional)
    contactName: string
    contactPhone: string
  }  // Required when `dangerousGoods` is true.
  customerReference?: string
  specialInstructions?: string
  alertAddresses?: {
    email: string
    phone?: string  // Mobile number for SMS alerts
    alertTypes: string[]  // Alert event types to subscribe to
  }[]  // TNT AU — email/SMS notifications for shipment events.
  keepInStore?: {
    numberOfDays: integer  // Number of business days to hold (1–5)
  }  // TNT AU — hold shipment at depot rather than attempting delivery.
  pickupBookingNumber?: string  // TNT AU — pre-arranged pickup booking reference
  extendedWarranty?: {
    value: number  // Declared value in AUD (max $10,000)
    class: A | B | C  // Warranty class tier
  }  // TNT AU — declare shipment value for extended warranty coverage.
  foodFreight?: boolean  // TNT AU — mark shipment as food freight
  bexAlerts?: {
    alertType: DESPATCHED | DELIVERY_STATUS | DELIVERED
    contactName: string
    emailAddress: string
  }[]  // BEX AU — email notifications for shipment events.
  timeSensitive?: {
    timeslot?: {
      dateTime: string  // Appointment datetime (ISO 8601)
      reference: string  // Appointment booking reference
    }  // Specific delivery appointment
    deliveryWindow?: {
      startDate: string
      endDate: string
      startTime?: string  // Earliest acceptable delivery time (HH:MM)
      endTime?: string  // Latest acceptable delivery time (HH:MM)
    }  // Date range delivery window
  }  // BEX AU — request a time-sensitive delivery. Provide either `timeslot` (specific appointment) or `deliveryWindow` (date range with optional time bounds).
  pallets?: {
    chep?: {
      exchangeIn?: integer
      exchangeOut?: integer
      directTransferToRec?: integer
      transferOffBex?: integer
      docketNumber?: string
    }
    loscam?: {
      exchangeIn?: integer
      exchangeOut?: integer
      directTransferToRec?: integer
      transferOffBex?: integer
      docketNumber?: string
    }
  }  // BEX AU — pallet exchange configuration for CHEP and/or LOSCAM.
  customerBarcodes?: string[]  // BEX AU — customer-supplied barcodes to associate with the consignment (max 50 chars each)
}

{
  orderNumber: string  // Booking reference issued by the carrier.
  consignmentNumber?: string | null  // Consignment/tracking number. Present immediately for some carriers (e.g. TNT AU); null for carriers that issue it asynchronously.
  barcodes?: string[]  // Carrier-issued barcode numbers for individual items in the consignment (BEX AU only)
  shipmentId: string  // Datashift shipment ID — use with `GET /shipments/{id}`, `GET /shipments/{id}/label`, and `POST /shipments/{id}/print`
  connectorId: string
  pickupStatus?: NOT_BOOKED | BOOKED | FAILED  // Outcome of the connector's auto-book-pickup setting, if enabled. `NOT_BOOKED` if auto-booking is off — call POST /pickups to book one explicitly.
  labelWarning?: string  // Present when the pickup booking failed (see pickupStatus) or the carrier returned a non-fatal warning alongside the label.
}

{
  shipmentId?: string  // Derived mode — book against this existing consignment. Omit for standalone.
  pickupDate: string
  readyTime: string
  closeTime: string
  serviceCode?: string  // TNT only — ignored by BEX
  collection?: BookingAddress  // Standalone mode only — required together with items and receiver
  items?: Items  // Standalone mode only — required together with collection and receiver
  receiver?: BookingAddress  // Standalone mode only — required together with collection and items
}

{
  pickupBookingId?: string
  orderNumber?: string | null
  status?: BOOKED | FAILED
  connectorId?: string
}

{
  id?: string
  tenantId?: string
  connectorId?: string
  carrier?: TNT_AU | BEX_AU
  status?: BOOKED | FAILED
  orderNumber?: string | null  // Carrier pickup reference. Null when status is FAILED.
  shipmentId?: string | null  // Null for a standalone pickup not derived from an existing consignment.
  pickupDate?: string
  readyTime?: string
  closeTime?: string
  serviceCode?: string | null  // TNT only.
  collection?: BookingAddress
  items?: Items
  lastErrorCode?: string | null
  lastErrorMessage?: string | null
  source?: API | PORTAL
  createdByUserId?: string | null  // Null for API-created bookings.
  createdAt?: string
}

{
  pickup: PickupBookingDetail
}

{
  id: string  // Datashift shipment ID
  carrier: TNT_AU | BEX_AU
  connectorName: string
  orderNumber: string
  consignmentNumber?: string | null  // Null if not yet assigned by the carrier
  status: CONSIGNED | CANCELLED
  pickupStatus?: NOT_BOOKED | BOOKED | FAILED
  serviceCode: string
  source: API | PORTAL  // Whether the shipment was booked via the API or the portal UI
  fromSuburb?: string | null
  toSuburb?: string | null
  createdAt: string
}

{
  total: integer  // Total shipment count for this tenant (may exceed the current page)
  limit: integer  // Page size used for this response
  offset: integer  // Offset used for this response
  shipments: ShipmentSummary[]
}

ShipmentSummary & {
  payer: Sender | Receiver | ThirdParty
  sender: BookingAddress
  collection: BookingAddress
  receiver: BookingAddress
  items: Items
  collectionDateTime: string
  collectionCloseTime: string
  customerReference?: string | null
  specialInstructions?: string | null
}

{
  shipment: ShipmentDetail
}

{
  timestamp: string
  status: string
  location?: string | null
  description?: string | null
}

{
  currentStatus: string
  eta?: string | null  // Estimated delivery date (YYYY-MM-DD)
  deliveredAt?: string | null  // Delivery timestamp, present only when delivered
  events: TrackingEvent[]  // Scan events in reverse-chronological order (most recent first)
}

{
  supported: boolean  // `false` when the matched carrier does not expose a tracking API
  tracking?: TrackingInfo  // Null if tracking is not yet available or not supported
}

{
  id: string  // Use as `deviceId` in print requests
  label: string  // Human-readable name for the device (set during registration)
  printerName?: string | null  // OS printer name reported by the device client, if available
  lastUsedAt?: string | null  // When this device last received a print job
  createdAt: string
}

{
  devices: PrintDevice[]
}

{
  deviceId: string  // ID of the print device to send the label to (from `GET /print-devices`)
}

{
  jobId: string  // Datashift print job ID
}

{
  message: string
  code: LABEL_NOT_AVAILABLE
}

{
  message: string
  code: LABEL_NOT_AVAILABLE | DEVICE_NOT_FOUND | SHIPMENT_NOT_FOUND
}

{
  message: string
  code?: string
}

{
  message: string
  errors?: {
    message: string
    field?: string  // Field path for validation errors (e.g. `sender.postcode`)
    code?: string  // Carrier error code for carrier-returned errors
  }[]  // Validation errors use `{ field, message }`; carrier errors use `{ code, message }`
}