openapi: 3.1.1
info:
  title: Shipment
  version: 2.0.0
  description: Schema definition for the Shipment entity in the Beckn Logistics domain.
  license:
    name: CC-BY-NC-SA 4.0 International
  contact:
    name: Beckn Labs
    url: https://beckn.io
components:
  schemas:
    Shipment:
      x-iri: https://schema.nfh.global/Shipment/v2.0
      type: object
      title: Shipment
      description: 'A Shipment represents the movement of one or more packages from an origin to a destination. It is the top-level fulfillment entity in a logistics transaction and maps to beckn:Fulfillment.

        '
      required:
      - id
      - status
      - origin
      - destination
      properties:
        id:
          type: string
          description: Unique identifier for the shipment
          example: SHP-2024-001234
        trackingId:
          type: string
          description: Public tracking identifier shared with sender/receiver
          example: TRK9876543210IN
        status:
          type: string
          description: Current status of the shipment
          enum:
          - CREATED
          - PICKUP_PENDING
          - PICKED_UP
          - IN_TRANSIT
          - AT_HUB
          - OUT_FOR_DELIVERY
          - DELIVERED
          - FAILED_DELIVERY
          - RETURNED
          - CANCELLED
          example: IN_TRANSIT
        origin:
          $ref: https://schema.nfh.global/LogisticsPlace/v2.0/attributes.yaml#/components/schemas/LogisticsPlace
        destination:
          $ref: https://schema.nfh.global/LogisticsPlace/v2.0/attributes.yaml#/components/schemas/LogisticsPlace
        packages:
          type: array
          description: List of packages in this shipment
          items:
            $ref: https://schema.nfh.global/Package/v2.0/attributes.yaml#/components/schemas/Package
        carrier:
          $ref: https://schema.nfh.global/Carrier/v2.0/attributes.yaml#/components/schemas/Carrier
        driver:
          $ref: https://schema.nfh.global/Driver/v2.0/attributes.yaml#/components/schemas/Driver
        vehicle:
          $ref: https://schema.nfh.global/Vehicle/v2.0/attributes.yaml#/components/schemas/Vehicle
        route:
          $ref: https://schema.nfh.global/Route/v2.0/attributes.yaml#/components/schemas/Route
        scheduledPickup:
          type: string
          format: date-time
          description: Scheduled pickup time
        estimatedDelivery:
          type: string
          format: date-time
          description: Estimated delivery date and time
        actualDelivery:
          type: string
          format: date-time
          description: Actual delivery date and time
        deliverySlot:
          $ref: https://schema.nfh.global/DeliverySlot/v2.0/attributes.yaml#/components/schemas/DeliverySlot
        serviceType:
          type: string
          description: Type of logistics service
          enum:
          - HYPERLOCAL
          - COURIER
          - INTERSTATE
          - LONG_HAUL
          - EXPRESS
          example: EXPRESS
        specialInstructions:
          type: string
          description: Special handling instructions for the shipment
          example: Handle with care. Do not tilt.
        proof:
          $ref: https://schema.nfh.global/Proof/v2.0/attributes.yaml#/components/schemas/Proof
        fare:
          $ref: https://schema.nfh.global/Fare/v2.0/attributes.yaml#/components/schemas/Fare
        receipt:
          $ref: https://schema.nfh.global/LogisticsReceipt/v2.0/attributes.yaml#/components/schemas/LogisticsReceipt
        cancellationPolicy:
          $ref: https://schema.nfh.global/CancellationPolicy/v2.0/attributes.yaml#/components/schemas/CancellationPolicy
        returnPolicy:
          $ref: https://schema.nfh.global/ReturnPolicy/v2.0/attributes.yaml#/components/schemas/ReturnPolicy
        alerts:
          type: array
          description: Alerts raised for this shipment
          items:
            $ref: https://schema.nfh.global/Alert/v2.0/attributes.yaml#/components/schemas/Alert
        trackingUpdates:
          type: array
          description: History of tracking updates
          items:
            $ref: https://schema.nfh.global/TrackingUpdate/v2.0/attributes.yaml#/components/schemas/TrackingUpdate
        createdAt:
          type: string
          format: date-time
          description: Timestamp when shipment was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of last update