Omniful, Inc. Returns API

openapi: 3.0.3
info:
  title: Omniful Integration APIs Background Jobs Returns 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: Returns
paths:
  /sales-channel/public/v1/seller/orders/{order_id}:
    post:
      summary: Create Return Request
      operationId: postCreateReturnRequest
      tags:
      - Returns
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              order_id: '10456114397478'
              return_reason: Damaged and Wrong Items-reject
              hub_code: '132'
              order_items:
              - sku_code: '8904355400626'
                return_quantity: 1
                return_reasons:
                - reason: Damaged
                  quantity: 1
              return_request_id: RO12348372969
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/return_orders/{id}/shipment:
    post:
      summary: Create Return Shipment
      operationId: postCreateReturnShipment
      tags:
      - Returns
      description: 'Endpoint Description This endpoint allows the user to create a shipment for a specific return order identified by :id. It is used to update the shipment details associated with a return order, including tracking information and package specifications. Request Body The request body must be in JSON format and should include the following parameters: tracking_url (string): A URL that provides tracking information for the shipment. awb_number (string): The Air Waybill number associated with the ship'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              tracking_url: https://tracking.fedex.com/123456789
              awb_number: 1124ee1231231232123213
              package_details:
                number_of_boxes: 1
                weight: 1
                dimensions:
                  length: 30
                  breadth: 20
                  height: 15
                remarks: Handle with care
              courier_partner:
                tag: jandt
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/return_orders/{id}/shipment/status:
    put:
      summary: Update Return Shipment Status
      operationId: putUpdateReturnShipmentStatus
      tags:
      - Returns
      description: 'Update Shipment Status for Return Orders This endpoint allows you to update the shipment status of a specific return order identified by its unique id. It is particularly useful for managing the logistics of returned items, enabling the system to track the status of shipments effectively. Request Body The request body must be in JSON format and should include the following parameter: shipment_status (string): The new status of the shipment. Following are the allowed values: "picked_up" "return_t'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              shipment_status: return_to_origin
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/seller/return_orders/{id}/shipment:
    post:
      summary: Create Seller Return Shipment
      operationId: postCreateSellerReturnShipment
      tags:
      - Returns
      description: This API endpoint is used to create shipment for any return order of the seller.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              tracking_url: https://tracking.fedex.com/123456789
              awb_number: '1732121312223122'
              package_details:
                number_of_boxes: 1
                weight: 1
                dimensions:
                  length: 30
                  breadth: 20
                  height: 15
                remarks: Handle with care
              courier_partner:
                tag: jandt
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/seller/return_orders/{id}/shipment/status:
    put:
      summary: Update Seller Return Shipment
      operationId: putUpdateSellerReturnShipment
      tags:
      - Returns
      description: This API endpoint is used to update the status of shipment for any return order of the seller.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              shipment_status: return_to_origin
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/orders/{order_id}/return_orders:
    post:
      summary: Create Return Order
      operationId: postCreateReturnOrder
      tags:
      - Returns
      description: '📌 Create Return Order API – Overview The Create Return Order API allows users to generate a customer return order against the provided order_id. This API helps sellers and platforms record returned items, capture return reasons, and apply any additional charges related to the return. 📌 Required Fields return_order_id → Unique identifier for the return order. return_items → Must include at least one returned item with: seller_sku_code return_quantity 📌 Request Body Parameters Field Data Type Desc'
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              return_order_id: RO1234561
              return_items:
              - sales_channel_item_id: iPhone 15 Pro
                sales_channel_return_item_id: iPhone 15 Pro
                seller_sku_code: iPhone 15 Pro
                return_quantity: 1
                return_reasons:
                - reason: Damaged item
                  quantity: 1
                unit_price: 50.0
                discount: 5.0
                total: 90.0
              additional_charges:
              - type: cod_fee
                cost: 5.0
                tax_inclusive: true
                tax_percentage: 10.0
                is_applied: true
              - type: return_shipment_fee
                cost: 8.0
                tax_inclusive: false
                tax_percentage: 5.0
                is_applied: true
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/returns/:
    post:
      summary: Create Return Requests
      operationId: postCreateReturnRequests
      tags:
      - Returns
      description: '📌 Create Return Request API – Overview The Create Return Request API is used to initiate a return request for orders that are in the delivered state. This API ensures efficient tracking and management of returned items by capturing essential details such as order ID, reasons for return, and hub information. 📌 Key Points to Consider The order must be in the delivered state before a return request can be created. Each return request must include: order_id return_reason hub_code (if applicable) ord'
      requestBody:
        content:
          application/json:
            example:
              order_id: shubhra-0009
              return_reason: Damaged and Wrong Item
              hub_code: Shubhra001
              order_items:
              - sku_code: iPhone 15 Pro
                return_quantity: 1
                return_reasons:
                - reason: Damaged
                  quantity: 1
                - reason: Wrong Item
                  quantity: 1
              return_request_id: omniful-1037
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/returns:
    get:
      summary: Get Return Requests
      operationId: getGetReturnRequests
      tags:
      - Returns
      description: '📌 Get Return Request API - Overview The Get Return Request API allows users to retrieve return requests for orders based on request status, order ID, and return order ID. 📌 Filters Available: order_id – Fetch return requests for a specific order. return_order_id – Retrieve details of a specific return request. status – Filter return requests by status. created_from - Filter return request by date of creation By default, return requests will be returned for the last 3 months only. The supported d'
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/returns/reject:
    put:
      summary: Reject Return Requests
      operationId: putRejectReturnRequests
      tags:
      - Returns
      description: 📌 Reject Return Request API - Overview The Reject Return Request API allows users to decline a return request for a specific return order ID. This API ensures that return requests can be managed efficiently by rejecting invalid or non-eligible returns.
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/returns/test-1026/approve:
    put:
      summary: Approve Return Request
      operationId: putApproveReturnRequest
      tags:
      - Returns
      description: '📌 Approve Return Request API - Overview The Approve Return Request API is used to approve return requests for an order based on its return order ID. This API allows users to approve full or partial returns and process refunds accordingly. 📌 Important Fields: Field Type Description order_id string Unique identifier for the order. order_items array of objects List of items being approved for return. order_items.sku_code string SKU code of the item being returned. order_items.return_quantity number'
      requestBody:
        content:
          application/json:
            example:
              order_id: test-1026
              order_items: []
              total_refundable_amount: 1
              approval_mode: full
              return_request_id: test-1026
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/return_orders/return_orders:
    get:
      summary: Get Return Orders
      operationId: getGetReturnOrders
      tags:
      - Returns
      description: 'Description: Retrieve a list of return orders with support for filtering by individual return order ID, multiple return order IDs, or the original sales channel order ID. Ideal for listing or searching return orders in bulk. Query Parameters Parameter Type Description return_order_id string Fetch return order by single ID return_order_ids array Fetch multiple return orders by ID list seller_sales_channel_order_id string Fetch by the external seller''s order ID'
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/return_orders/{return_order_id}:
    get:
      summary: Get Return Order by ID
      operationId: getGetReturnOrderById
      tags:
      - Returns
      description: 'Endpoint Description: Fetch complete details of a single return order by its unique ID, including customer info, returned items, status, pickup address, QC details, and shipment information. Path Parameters Parameter Type Description return_order_id string The unique return order ID'
      parameters:
      - name: return_order_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/seller/orders/{order_id}/{return_} request_id/approve:
    put:
      summary: Approve Return Request
      operationId: putApproveReturnRequest2
      tags:
      - Returns
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      - name: return_
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              order_id: '10455642964262'
              order_items:
              - sku_code: '132'
                return_quantity: 1
                return_reasons:
                - reason: Damaged
                  quantity: 1
              total_refundable_amount: 100
              approval_mode: full
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/seller/orders/{order_id}/reject:
    put:
      summary: Reject Return Request
      operationId: putRejectReturnRequest
      tags:
      - Returns
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/seller/orders/{order_id}/return_order:
    post:
      summary: Create Return Order
      operationId: postCreateReturnOrder2
      tags:
      - Returns
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              return_order_id: RO12345678931
              return_items:
              - sales_channel_item_id: '17032658518311'
                sales_channel_return_item_id: '17032658518311'
                seller_sku_code: mohi-sku-5-shopify-100-100
                return_quantity: 1
                return_reasons:
                - reason: Damaged item - test
                  quantity: 1
                unit_price: 100.0
                discount: 10.0
                total: 90.0
              additional_charges:
              - type: cod_fee
                cost: 0.0
                tax_inclusive: true
                tax_percentage: 10.0
                is_applied: true
              - type: return_shipment_fee
                cost: 8.0
                tax_inclusive: false
                tax_percentage: 5.0
                is_applied: true
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/seller/return_orders:
    get:
      summary: Get Seller Return Order (To Be Deprecated)
      operationId: getGetSellerReturnOrderToBeDeprecated
      tags:
      - Returns
      description: This API endpoint is used for getting all Return Orders of the seller.
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v1/seller/return_requests:
    get:
      summary: Get Seller Return Requests
      operationId: getGetSellerReturnRequests
      tags:
      - Returns
      description: '📌 Get Seller Return Request API - Overview The Get Seller Return Request API allows users to retrieve return requests for orders based on request status, order ID, and return order ID. 📌 Filters Available: order_id – Fetch return requests for a specific order. status – Filter return requests by status. created_from - Filter return request by date of creation created_to - Filter return request by date of creation By default, return requests will be returned for the last 3 months only. The support'
      responses:
        '200':
          description: Successful response
  /sales-channel/public/v2/seller/return_orders:
    get:
      summary: Get Seller Return Orders
      operationId: getGetSellerReturnOrders
      tags:
      - Returns
      responses:
        '200':
          description: Successful response
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer