openapi: 3.0.3
info:
title: Omniful Integration APIs Background Jobs Orders 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: Orders
paths:
/sales-channel/public/v1/orders:
post:
summary: Create Order
operationId: postCreateOrder
tags:
- Orders
description: 📌 Create Order API Overview The Create Order API allows users to place new orders in Omniful by providing order details, customer information, shipping and billing addresses, invoice details, and payment information. 📝 Request Body Parameters Key Data Type Description Required order_id string Must be a globally unique identifier for the order (e.g., "order_0008"). Cannot be reused if the order is deleted. ✅ Yes order_alias string Secondary identifier for tracking in external systems (e.g., ERP o
requestBody:
content:
application/json:
example:
shipment_type: omniful_generated
order_id: order_no__1
order_alias: order_omniful-alias
hub_code: locoff
order_items:
- sku_code: UT-TSHIRT-WHT-S-17
name: iPhone 15 Pro
display_price: 799
selling_price: 699
is_substituted: false
quantity: 1
tax_percent: 10
tax: 69.9
unit_price: 699
subtotal: 699
total: 768.9
discount: 100
tax_inclusive: true
billing_address:
address1: 123 Al-Masjid Al-Haram Street
address2: Near Al-Faisaliah Tower
city: Riyadh
country: Saudi Arabia
first_name: John
last_name: Doe
phone: +966-11-234-5678
state: Riyadh
zip: '11564'
area: Al Olaya
district: Riyadh
street: Kings Road
state_code: RIY
country_code: SA
latitude: 24.7136
longitude: 46.6753
national_address_code: code
shipping_address:
address1: 456 King Abdulaziz Road
address2: Near Kingdom Centre
city: Jeddah
country: Saudi Arabia
first_name: Jane
last_name: Smith
phone: +966-12-345-6789
state: Makkah
zip: '21577'
area: Al Olaya
district: Riyadh
street: Kings Road
state_code: MKA
country_code: SA
latitude: 21.4225
longitude: 39.8262
national_address_code: code
invoice:
currency: USD
subtotal: 699
shipping_price: 0
shipping_refund: 0
tax: 69.9
discount: 100
total: 768.9
total_paid: 768.9
total_due: 0
total_refunded: 0
payment_mode: Credit Card
tax_percent: 10
shipping_tax: 0
sub_total_tax_inclusive: true
sub_total_discount_inclusive: true
shipping_tax_inclusive: false
shipping_discount_inclusive: false
customer:
id: 66ced351ffed27dec7c4072a
first_name: John
last_name: Doe
mobile: '1234567890'
mobile_code: '+1'
email: john.doe@example.com
avatar: https://example.com/avatar.jpg
gender: male
labels:
- label1
- label2
- label3
slot:
delivery_date: '18122024'
start_time: 1100
end_time: 1500
payment_method: prepaid
delivery_type: normal_delivery
is_cash_on_delivery: false
note: Please deliver during weekdays
type: b2b
external_fields:
- key: order_id
value: '12345'
- key: customer_name
value: John Doe
- key: status
value: shipped
cancel_order_after_seconds: 30
attachments:
- name: Bill
description: Bill description
url: http://omniful-local-uploads.s3.eu-central-1.localstack.oceaninfra.localhost/orders/orders/attachments/98bf916bcb364c1656b0aca4a103b5ea71780922501.jpeg
mime_type: image/jpeg
entity: invoice
responses:
'200':
description: Successful response
put:
summary: Update Order
operationId: putUpdateOrder
tags:
- Orders
description: 📌 Update Order API - Overview The Update Order API allows users to modify the details of an existing order that was previously placed. This API can be used to update various order attributes, such as order items, shipping details, billing information, and customer details. Users can update an order only if it is not in the "packed" state. Once an order reaches the packed stage, further modifications using this API are restricted. This API ensures flexibility in managing orders before final proce
requestBody:
content:
application/json:
example:
order_id: order_0003
hub_code: Shubhra001
order_items:
- sku_code: iPhone 15 Pro
name: iPhone 15 Pro
display_price: 799
selling_price: 699
is_substituted: false
quantity: 2
tax_percent: 10
tax: 69.9
unit_price: 699
subtotal: 699
total: 768.9
discount: 100
tax_inclusive: true
billing_address:
address1: 123 Main Street
city: New York
country: United States
first_name: John
last_name: Doe
phone: 123-456-7890
state: NY
zip: '10001'
state_code: NY
country_code: US
latitude: 40.7128
longitude: -74.006
national_address_code: code
shipping_address:
address1: 456 Elm Street
city: Los Angeles
country: United States
first_name: Jane
last_name: Smith
phone: 987-654-3210
state: CA
zip: '90001'
state_code: CA
country_code: US
latitude: 34.0522
longitude: -118.2437
national_address_code: code
order_created_at: '2023-07-28T09:00:00Z'
invoice:
currency: USD
subtotal: 699
shipping_price: 0
shipping_refund: 0
tax: 69.9
discount: 100
total: 768.9
total_paid: 768.9
total_due: 0
total_refunded: 0
payment_method: Credit Card
tax_percent: 10
shipping_tax: 0
sub_total_tax_inclusive: true
sub_total_discount_inclusive: true
shipping_tax_inclusive: false
shipping_discount_inclusive: false
customer:
first_name: John
last_name: Doe
mobile: '1234567890'
mobile_code: '+1'
email: john.doe@example.com
avatar: https://example.com/avatar.jpg
gender: male
shipment:
shipping_partner_name: CourierX
shipping_partner_tag: courierx123
awb_number: AWB-456
awb_label: https://example.com/awb-label.jpg
tracking_link: https://example.com/tracking/456
shipment_method: auto-ship
payment_method: prepaid
is_cash_on_delivery: false
note: Please deliver during weekdays
external_fields:
- key: order_id_1
value: '12347'
- key: customer_name
value: John Doe
cancel_order_after_seconds: 30
responses:
'200':
description: Successful response
/sales-channel/public/v1/invoice/{order_id}:
put:
summary: Update Order Invoice
operationId: putUpdateOrderInvoice
tags:
- Orders
description: 📌 Update Order Invoice API - Overview The Update Order Invoice API allows users to modify the invoice details of a previously placed order. This API is useful when adjustments or modifications are required in the invoice amount, tax details, discounts, payment information, or other financial components of an order. Users can use this API to ensure that the invoice reflects the correct pricing and charges before final processing or fulfillment. To successfully update an invoice, all the fields fr
parameters:
- name: order_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json: {}
responses:
'200':
description: Successful response
/sales-channel/public/v1/orders/{order_id}/attachments:
put:
summary: Update Order Attachments
operationId: putUpdateOrderAttachments2
tags:
- Orders
description: 'Overview Updates attachments for an existing order. Use this request to add or update attachment metadata for the specified order, such as invoice or order. Endpoint PUT {{base_url}}/public/v1/orders/{{order_id}}/attachments Authentication This request uses the configured access token variable: {{access_token}} Validation Notes The attachments array can contain a maximum of 10 items. Path Parameters Parameter Type Required Description order_id string Yes The unique identifier of the order whose '
parameters:
- name: order_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
attachments:
- name: Bill
description: Bill description
url: http://omniful-local-uploads.s3.eu-central-1.localstack.oceaninfra.localhost/orders/orders/attachments/98bf916bcb364c1656b0aca4a103b5ea71780922501.jpeg
mime_type: image/jpeg
entity: order
- name: Bill 2
description: Bill 2 description
url: http://omniful-local-uploads.s3.eu-central-1.localstack.oceaninfra.localhost/orders/orders/attachments/98bf916bcb364c1656b0aca4a103b5ea71780922501.jpeg
mime_type: image/jpeg
entity: invoice
responses:
'200':
description: Successful response
/sales-channel/public/v1/orders/{order_id}/cancel:
put:
summary: Cancel Order
operationId: putCancelOrder
tags:
- Orders
description: 📌 Overview The Cancel Order API allows users to cancel an existing order by providing a cancellation reason. Field Type Required Description cancel_reason string ✅ Yes Reason for canceling the order.
parameters:
- name: order_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
cancel_reason: Not needed now.
responses:
'200':
description: Successful response
/sales-channel/public/v1/orders/{order_id}/approve:
put:
summary: Approve Order
operationId: putApproveOrder
tags:
- Orders
description: 📌 Approve Order API - Overview The Approve Order API is used to manually approve orders that require user authorization before processing. This API ensures that orders needing validation, review, or confirmation are not automatically processed without approval. Once an order is approved, it can proceed to the next stage in the fulfillment workflow, such as packing and shipping.
parameters:
- name: order_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
/sales-channel/public/v1/seller/orders:
get:
summary: Get Seller Orders (⚠️ To be deprecated on 30-07-2026)
operationId: getGetSellerOrdersToBeDeprecatedOn30072026
tags:
- Orders
description: 📌 Get Seller Orders API - Overview The Get Seller Orders API allows users to retrieve a list of all orders for a specific seller who has integrated a Custom Integration on their dashboard. This API enables sellers to fetch and manage orders placed within the last three months, providing real-time visibility into their order history. It is useful for tracking order statuses, processing fulfillment, and analyzing order trends over time. 📝 Response Body Parameters Field Data Type Description Always
responses:
'200':
description: Successful response
/sales-channel/public/v1/seller/orders/{order_id}:
get:
summary: Get Seller Order By OrderID
operationId: getGetSellerOrderByOrderid
tags:
- Orders
description: 📌 Get Seller Order by Order ID API - Overview The Get Seller Order by Order ID API allows users to fetch details of a single order for a seller using the Omniful-generated Order ID (omniful_order_id). This API is particularly useful for retrieving order details that were not placed through the Custom Sales Channel Integration. It provides complete order information, including order items, customer details, billing and shipping addresses, and invoice details, ensuring sellers have full visibility
parameters:
- name: order_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
/sales-channel/public/v1/orders/{order_id}/logs:
get:
summary: Get Order Logs (⚠️ To be deprecated on 30-07-2026)
operationId: getGetOrderLogsToBeDeprecatedOn30072026
tags:
- Orders
description: '📌 Get Order Logs API – Overview The Get Order Logs API allows users to retrieve detailed logs for a specific order using its Order ID. It provides real-time insights into the order’s lifecycle within the warehouse, including: Status updates Fulfillment progress Modifications made to the order This API is particularly useful for: Tracking order history Troubleshooting operational issues Ensuring seamless order management Response Body Parameters Field Data Type Description Always Included is_succ'
parameters:
- name: order_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
/sales-channel/public/v1/seller/orders/{system_order_id}/logs:
get:
summary: Get Seller Order Logs
operationId: getGetSellerOrderLogs
tags:
- Orders
description: '📌 Get Order Logs API – Overview The Get Order Logs API allows users to retrieve detailed logs for a specific order using System Order ID. It provides real-time insights into the order’s lifecycle within the warehouse, including: Status updates Fulfillment progress Modifications made to the order This API is particularly useful for: Tracking order history Troubleshooting operational issues Ensuring seamless order management Response Body Parameters Field Data Type Description Always Included is_s'
parameters:
- name: system_order_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
/sales-channel/public/v1/orders/{order_id}/shipping_address:
put:
summary: Update Shipping Address
operationId: putUpdateShippingAddress
tags:
- Orders
description: 📌 Update Shipping Address API – Overview The Update Shipping Address API allows users to modify the shipping address details of an order until it reaches the shipped state. This API provides flexibility in updating recipient details, address, and contact information, helping Prevent delivery issues, Ensure accurate fulfillment, Maintain customer satisfaction. Users can only update the shipping address associated with a specific Order ID. Users can only update the shipping address associated with
parameters:
- name: order_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
address1: 123 Main St
address2: Apt 4B
city: New York
country: USA
first_name: John
last_name: Doe
phone_number: '7044063694'
country_calling_code: '+91'
country_code: IN
state: NY
area: Manhattan
district: Downtown
street: Broadway
zip: '10001'
state_code: NY
latitude: 40.7128
longitude: -74.006
national_address_code: nac_1234
responses:
'200':
description: Successful response
/sales-channel/public/v1/orders/{order_id}/shipping_details:
put:
summary: Update Shipping Details
operationId: putUpdateShippingDetails
tags:
- Orders
description: 📌 Update Shipping Details API - Overview The Update Shipping Details API allows users to modify the shipping details for an order until it reaches the shipped state. This API ensures flexibility in updating recipient details, address, and contact information for a particular order, preventing delivery issues and ensuring accurate fulfillment. Users can only update the shipping address associated with a specific Order ID. Fields to be updated cannot be empty. No more than two fields can be update
parameters:
- name: order_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
fields_to_update:
- slot
- address
address:
address1: 129 Main Street
address2: Apt 4B
city: New York
country: United States
first_name: John
last_name: Doe
phone: +1 212-555-1234
country_calling_code: '+1'
country_code: US
state: New York
area: Manhattan
district: Downtown
zip: '10001'
state_code: NY
latitude: 40.712776
longitude: -74.005974
email: johndoe@example.com
national_address_code: nac_1234
slot:
delivery_date: '12012026'
start_time: 1500
end_time: 2059
responses:
'200':
description: Successful response
/sales-channel/public/v1/tenants/sellers/{seller_code}/orders:
get:
summary: Get Orders (⚠️ To be deprecated on 30-07-2026))
operationId: getGetOrdersToBeDeprecatedOn30072026
tags:
- Orders
description: 'Description Retrieve a paginated list of orders for a specific seller. You can filter results using multiple optional query parameters such as order ID, customer details, AWB number, SKU code, status, types, and date range. Path Parameters Name Type Required Description seller_code string Yes Unique seller identifier in Omniful. Query Parameters Name Type Required Description page integer No Page number for pagination (default: 1). per_page integer No Number of records per page (default: 20). or'
parameters:
- name: seller_code
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
post:
summary: Create Order
operationId: postCreateOrder3
tags:
- Orders
description: 📌 Create Order API Overview The Create Order API allows users to place new orders in Omniful by providing order details, customer information, shipping and billing addresses, invoice details, and payment information. 📝 Request Body Parameters Key Data Type Description Required order_id string Must be a globally unique identifier for the order (e.g., "order_0008"). Cannot be reused if the order is deleted. ✅ Yes order_alias string Secondary identifier for tracking in external systems (e.g., ERP o
parameters:
- name: seller_code
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
order_id: order-128
order_alias: order-alias-128
hub_code: locoff
shipment_type: sales_channel_generated
order_items:
- sku_code: UT-TSHIRT-WHT-S-17
name: iPhone 200
display_price: 799
selling_price: 699
is_substituted: false
quantity: 1
tax_percent: 10
tax: 69.9
unit_price: 699
subtotal: 699
total: 768.9
discount: 100
tax_inclusive: true
billing_address:
address1: 123 Al-Masjid Al-Haram Street
address2: Near Al-Faisaliah Tower
city: Riyadh
country: Saudi Arabia
first_name: John
last_name: Doe
phone: +966-11-234-5678
state: Riyadh
zip: '11564'
area: Al Olaya
district: Riyadh
street: Kings Road
state_code: RIY
country_code: SA
latitude: 24.7136
longitude: 46.6753
national_address_code: ''
shipping_address:
address1: 456 King Abdulaziz Road
address2: Near Kingdom Centre
city: Jeddah
country: Saudi Arabia
first_name: Jane
last_name: Smith
phone: +966-12-345-6789
state: Makkah
zip: '21577'
area: Al Olaya
district: Riyadh
street: Kings Road
state_code: MKA
country_code: SA
latitude: 21.4225
longitude: 39.8262
national_address_code: ''
invoice:
currency: SAR
subtotal: 699
shipping_price: 0
shipping_refund: 0
tax: 69.9
discount: 100
total: 768.9
total_paid: 768.9
total_due: 0
total_refunded: 0
payment_method: Credit Card
tax_percent: 10
shipping_tax: 0
sub_total_tax_inclusive: true
sub_total_discount_inclusive: true
shipping_tax_inclusive: false
shipping_discount_inclusive: false
customer:
id: 66ced351ffed27dec7c4072a
first_name: John
last_name: Doe
mobile: '1234567890'
mobile_code: '+1'
email: john.doe@example.com
avatar: https://example.com/avatar.jpg
gender: male
labels:
- label1
- label2
- label3
slot:
delivery_date: '18122024'
start_time: 1100
end_time: 1500
payment_method: prepaid
delivery_type: normal_delivery
is_cash_on_delivery: false
note: Please deliver during weekdays
type: b2b
meta_data:
name: Metadata
has_options: true
external_fields:
- key: order_id
value: '12345'
- key: customer_name
value: John Doe
- key: status
value: shipped
attachments:
- name: Bill
description: Bill description
url: http://omniful-local-uploads.s3.eu-central-1.localstack.oceaninfra.localhost/orders/orders/attachments/98bf916bcb364c1656b0aca4a103b5ea71780922501.jpeg
mime_type: image/jpeg
entity: order
- name: Bill 2
description: Bill 2 description
url: http://omniful-local-uploads.s3.eu-central-1.localstack.oceaninfra.localhost/orders/orders/attachments/98bf916bcb364c1656b0aca4a103b5ea71780922501.jpeg
mime_type: image/jpeg
entity: invoice
responses:
'200':
description: Successful response
/sales-channel/public/v1/tenants/sellers/{seller_code}/orders/{id}:
get:
summary: Get Single Order
operationId: getGetSingleOrder
tags:
- Orders
description: Description Retrieve full details of a specific order for a seller using the id which is the omniful order id. Path Parameters Name Type Required Description seller_code string Yes Unique identifier for the seller (e.g., KO-SE-1). id string Yes Unique internal Omniful order identifier used to fetch a specific order.
parameters:
- name: seller_code
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
put:
summary: Update Order
operationId: putUpdateOrder2
tags:
- Orders
description: 📌 Update Order API - Overview The Update Order API allows users to modify the details of an existing order that was previously placed. This API can be used to update various order attributes, such as order items, shipping details, billing information, and customer details. Users can update an order only if it is not in the "packed" state. Once an order reaches the packed stage, further modifications using this API are restricted. This API ensures flexibility in managing orders before final proce
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:
order_id: order_000081
hub_code: ONLS
shipment_type: sales_channel_generated
order_items:
- sku_code: iPhone 15 Pro
name: iPhone 15 Pro
display_price: 799
selling_price: 699
is_substituted: false
quantity: 2
tax_percent: 10
tax: 69.9
unit_price: 699
subtotal: 699
total: 768.9
discount: 100
tax_inclusive: true
billing_address:
address1: 123 Main Street
city: New York
country: United States
first_name: John
last_name: Doe
phone: 123-456-7890
state: NY
zip: '10001'
state_code: NY
country_code: US
latitude: 40.7128
longitude: -74.006
national_address_code: ''
shipping_address:
address1: 456 Elm Street
city: Los Angeles
country: United States
first_name: Jane
last_name: Smith
phone: 987-654-3210
state: CA
zip: '90001'
state_code: CA
country_code: US
latitude: 34.0522
longitude: -118.2437
national_address_code: ''
order_created_at: '2023-07-28T09:00:00Z'
invoice:
currency: USD
subtotal: 699
shipping_price: 0
shipping_refund: 0
tax: 69.9
discount: 100
total: 768.9
total_paid: 768.9
total_due: 0
total_refunded: 0
payment_method: Credit Card
tax_percent: 10
shipping_tax: 0
sub_total_tax_inclusive: true
sub_total_discount_inclusive: true
shipping_tax_inclusive: false
shipping_discount_inclusive: false
customer:
first_name: John
last_name: Doe
mobile: '1234567890'
mobile_code: '+1'
email: john.doe@example.com
avatar: https://example.com/avatar.jpg
gender: male
shipment:
shipping_partner_name: CourierX
shipping_partner_tag: courierx123
awb_number: AWB-456
awb_label: https://example.com/awb-label.jpg
tracking_link: https://example.com/tracking/456
labels:
- label4
- label5
- label6
payment_method: prepaid
is_cash_on_delivery: false
note: Please deliver during weekdays
meta_data:
name: detadata
has_options: true
external_fields:
- key: order_id_1
value: '12347'
- key: customer_name
value: John Doe
responses:
'200':
description: Successful response
/sales-channel/public/v1/tenants/sellers/{seller_code}/orders/{id}/cancel:
post:
summary: Cancel Order
operationId: postCancelOrder
tags:
- Orders
description: 'Description Cancel an existing order for a specific seller in Omniful. This endpoint is used when an order needs to be cancelled due to customer request, incorrect product selection, or operational reasons. Only orders in a cancellable state (e.g., not yet shipped or delivered) can be cancelled. Path Parameters Name Type Required Description seller_code string Yes Unique identifier for the seller (e.g., KO-SE-2). id string Yes Internal Omniful order ID of the order to be cancelled. Request Body '
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:
cancel_reason: The customer selected the wrong product.
responses:
'200':
description: Successful response
/sales-channel/public/v1/tenants/sellers/{seller_code}/orders/bulk:
post:
summary: Bulk Create Orders
operationId: postBulkCreateOrders
tags:
- Orders
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/omniful-inc/refs/heads/main/openapi/omniful-inc-orders-api-openapi.yml