Omniful, Inc. Shipment API

openapi: 3.0.3
info:
  title: Omniful Integration APIs Background Jobs Shipment API
  version: v1
  description: Omniful unified supply chain and fulfillment platform integration APIs (Order Management, Warehouse/Inventory, Returns, Purchase Orders, Shipment/TMS, Webhooks). Derived faithfully from the provider-published Postman collection at docs.omniful.tech; paths, methods, parameters, and request examples are as published, response schemas are not enumerated in the source.
  contact:
    url: https://docs.omniful.tech
servers:
- url: https://prodapi.omniful.com
security:
- bearerAuth: []
tags:
- name: Shipment
paths:
  /sales-channel/public/v1/orders/{order_id}/shipment:
    post:
      summary: Trigger Shipment
      operationId: postTriggerShipment
      tags:
      - Shipment
      description: '📌 Create Shipment API – Overview The Create Shipment API is used to generate shipments for orders in Omniful. This API allows users to: Assign a shipping partner Generate tracking numbers (AWB) Set shipment details Note: The API only supports orders with the shipment type set to Omniful Generated. Orders with other shipment types are not eligible for shipment creation through this API. Request Body Parameters Field Data Type Description Required number_of_boxes number Total number of packages to'
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              number_of_boxes: 1
              weight: 1.2
              remarks: Please handle shipment carefully,
      responses:
        '200':
          description: Successful response
    put:
      summary: Add Shipment Details
      operationId: putAddShipmentDetails
      tags:
      - Shipment
      description: '📌 Add Shipment Details API – Overview The Add Shipment Details API allows users to add existing shipment details for an order. This API is typically used to update shipment-related information such as: Tracking numbers (AWB) Courier service details Delivery tracking URLs 📌 Key Information This API applies only to orders where the shipment type is either: sales_channel_generated sales_channel_notified If the shipment was created by the sales channel, users can update the shipment details as requi'
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              tracking_url: https://tracking.fedex.com/123456789
              awb_number: AWB123456787
              awb_label: https://tracking.fedex.com/123456789.pdf
              package_details:
                number_of_boxes: 1
                weight: 1
                dimensions:
                  length: 30
                  breadth: 20
                  height: 15
                remarks: Handle with care
              courier_partner:
                tag: dhl_express
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/orders/{order_id}/shipment/status:
    put:
      summary: Update Shipment Status
      operationId: putUpdateShipmentStatus
      tags:
      - Shipment
      description: '📌 Update Shipment Status API - Overview The Update Shipment Status API allows users to update the shipment status of an order, ensuring real-time tracking updates for better shipment visibility. 📌 Supported Shipment Types: Manual Shipment (omniful_generated) – Shipments created manually by users. Sales Channel Generated Shipment (sales_channel_generated) – Shipments generated by the sales channel system. Sales Channel Notified Shipment (sales_channel_notified) – Shipments updated based on notifi'
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              shipment_status: dispatched
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/tenants/sellers/{seller_code}/orders/{id}/shipment:
    post:
      summary: Trigger Automatic Shipment Creation
      operationId: postTriggerAutomaticShipmentCreation
      tags:
      - Shipment
      description: This API endpoint is used to trigger the automatic creation of a shipment for a specific order within the Omniful platform. The shipment is generated when the details for a given order are provided, such as the number of boxes, weight, and any special remarks. This is used when the shipments are to be generated automatically by Omniful.
      parameters:
      - name: seller_code
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              number_of_boxes: 1
              weight: 1.2
              remarks: Please handle shipment carefully,
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/tenants/sellers/{seller_code}/orders/{order_id}/shipment:
    put:
      summary: Update Shipment Details
      operationId: putUpdateShipmentDetails
      tags:
      - Shipment
      description: This API endpoint is used to update an existing shipment for a specific order within the Omniful platform. It allows you to modify shipment details such as shipping partner information, tracking URL, package details (e.g., dimensions, weight), and courier partner information. This is typically used to update shipment details after the initial creation by Sales Channel only.
      parameters:
      - name: seller_code
        in: path
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              tracking_url: https://tracking.fedex.com/123456789
              awb_number: AWB123456787
              awb_label: https://omniful-staging-uploads.s3.eu-central-1.amazonaws.com/shipping/tamex/pixicommerce435/14755/55f86b562b59de7e04cc5687_awb_label.pdf
              package_details:
                number_of_boxes: 1
                weight: 1
                dimensions:
                  length: 30
                  breadth: 20
                  height: 15
                remarks: Handle with care
              courier_partner:
                tag: dhl_express
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/tenants/sellers/{seller_code}/orders/{order_id}/shipment/status:
    put:
      summary: Update Shipment Status
      operationId: putUpdateShipmentStatus2
      tags:
      - Shipment
      description: 'This API is used to update shipment status when shipment type of the order is sales_channel_generated & omniful_generated. Allowed Shipment Status: [ dispatched, out_for_delivery, in_transit, delivered, return_to_origin]'
      parameters:
      - name: seller_code
        in: path
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              shipment_status: delivered
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/tenants/sellers/{seller_code}/orders/{oms_order_id}/shipment/manual:
    post:
      summary: Create Manual Shipment
      operationId: postCreateManualShipment
      tags:
      - Shipment
      description: 'Creates a manual shipment for an existing order by attaching tracking, AWB, and package details.Can be created only for order with the shipment type: omniful_generated'
      parameters:
      - name: seller_code
        in: path
        required: true
        schema:
          type: string
      - name: oms_order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              tracking_url: https://tracking.example.com/123456789
              awb_number: AWBMANUAL1234511618882661132
              awb_label: https://example.link.com/shipping/b59de7e04cc5687_awb_label.pdf
              package_details:
                number_of_boxes: 1
                weight: 1
                dimensions:
                  length: 30
                  breadth: 20
                  height: 15
                remarks: Handle with care
      responses:
        '200':
          description: Successful response
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer