Use Cases of createOrder API
The createOrder API supports various order creation scenarios to accommodate different business requirements and customer needs. Each use case represents a specific configuration or feature combination that can be utilized when placing orders through the platform.
Below is the use case example for each use-case in the createOrder API.
1. Create Basic Order
The basic order creation use case represents the standard order placement flow where a customer places a home delivery order with essential information. This includes shipment details with line items containing seller identifiers, quantities, and monetary values such as amount paid, effective price, and marked price. The order includes payment method details specifying the gateway, mode of payment, payment identifier, and transaction party information indicating who bears the refund and collection responsibilities. Both billing and shipping details are provided with complete address information including name, contact details, location coordinates, and address type. The order also specifies currency details, channel location, order platform, and allows for location reassignment if needed. This serves as the foundation for all other order types and demonstrates the minimum required fields for successful order creation.
2. Create MTO Order
Made-to-order (MTO) orders are created when products need to be manufactured or assembled after the order is placed rather than being shipped from existing inventory. This use case is similar to the basic order but includes the is_mto flag set to true at the shipment level, indicating that the fulfillment process will involve production or customization before shipping. The system handles these orders differently by allowing extended processing times and potentially different fulfillment workflows compared to standard inventory-based orders.
3. Create B2B Order
Business-to-business orders are distinguished by the inclusion of a GST identification number (GSTIN) in the order payload. This use case enables companies to place orders for their business needs with proper tax documentation. The b2b_gstin_number field contains the business's GST registration number, which is essential for tax compliance and invoicing in business transactions. All other order details remain similar to standard orders, but the presence of GSTIN triggers different tax calculation and invoicing processes appropriate for B2B commerce.
4. Create Order With Applied Coupon
This use case demonstrates order creation when a customer applies a promotional coupon or discount code during checkout. The order includes coupon_details containing the coupon code, unique identifier, ownership information specifying which party is responsible for the discount, and flags indicating whether returns and cancellations are allowed for coupon-discounted items. The monetary values reflect the discount applied through coupon_discount field, and the total amount paid accounts for both regular discounts and coupon discounts. This enables customers to benefit from promotional offers while maintaining proper tracking of discount attribution and associated policies.
5. Create Order With Special Instructions
Customers can provide specific delivery or handling instructions when placing orders through this use case. The special_instructions field at the line item level allows customers to communicate important details such as delivery preferences, handling requirements, or any other relevant information that should be considered during fulfillment. These instructions are preserved with the order and can be used by fulfillment teams, delivery partners, or customer service representatives to ensure the order is processed according to customer expectations.
6. Create Order with Shipment and Order Level Tags
Tags provide a flexible way to categorize, filter, and organize orders for various business purposes such as marketing campaigns, fulfillment routing, or analytics. This use case demonstrates the ability to add tags at both the shipment level and the order level. Shipment-level tags can be used to categorize individual shipments within an order, while order-level tags apply to the entire order. These tags enable businesses to segment orders for reporting, workflow automation, or special handling without modifying the core order structure.
7. Create Order with Custom Taxation at Line Item Level
When standard tax calculations are insufficient or when specific tax rules need to be applied, this use case allows for custom taxation configuration at the line item level. The tax_details field includes tax_rule_id and hs_code (Harmonized System code) which enable precise tax calculation based on product classification, origin, destination, or other business-specific tax rules. This is particularly useful for products with special tax treatment, cross-border transactions, or when integrating with external tax calculation systems. The shipping_by configuration is set to Seller, indicating that the seller manages shipping and potentially tax collection.
8. Create Order with Courier Partner
This use case enables explicit specification of a courier partner for order fulfillment rather than relying on automatic assignment. The courier_partner_details include the scheme identifier, extension identifier, delivery time commitments with minimum and maximum TAT (Turnaround Time), partner name, area code routing information, quality check support status, self-shipment indicators, credential usage, and maximum reattempt limits. This allows businesses to have granular control over shipping partners, especially useful when specific courier relationships, service levels, or delivery commitments need to be maintained for certain orders or customer segments.
9. Create Order with Shipment Level Lifecycle Messages
Lifecycle messages provide a mechanism to display informational, warning, or error messages to customers at specific stages of the order fulfillment process. This use case demonstrates the ability to configure messages at both shipment and order levels. Each message includes the message content, type (such as INFO), the order states when the message should be displayed, and a priority level. These messages can be used to communicate important information about order status, delivery expectations, special handling requirements, or any other relevant updates that customers should be aware of during the order lifecycle.
10. Create Order with Promise Details
Promise details allow businesses to set explicit delivery time commitments for orders, providing customers with expected delivery windows. This use case includes promise_details at the shipment level with min_sla and max_sla timestamps representing the earliest and latest expected delivery times. These service level agreements help manage customer expectations and enable better planning for both customers and fulfillment teams. The promise details can be used for customer communication, delivery partner assignment, and performance tracking against committed delivery times.
11. Create Draft Order
Draft orders, also known as pendency orders, are orders that are created but not immediately processed for fulfillment. This use case includes the is_draft flag set to true, which prevents the order from entering the active fulfillment workflow. Draft orders are useful for scenarios where order information needs to be collected incrementally, payment needs to be confirmed separately, or when orders require manual review before processing. These orders can be converted to active orders later through an update operation, allowing businesses to implement multi-step order creation workflows or hold orders pending additional verification.
12. Create Scheduled Order
Scheduled orders allow businesses to create orders that should not be processed until a specific future date and time. This use case includes the allow_processing_after field at the shipment level with a timestamp indicating when order processing should begin. This is useful for scenarios such as pre-orders, backorders, or when customers want to schedule deliveries for future dates. The system holds these orders until the specified time, at which point they transition to active status and enter the normal fulfillment workflow.
13. Create Order with Order, Shipment and Line Item Meta
Metadata fields provide a flexible mechanism to store additional custom information at various levels of the order hierarchy without modifying the core order schema. This use case demonstrates the ability to include meta fields at the order level, shipment level, and line item level. Each meta field can contain key-value pairs of custom data that can be used for integration with external systems, storing business-specific information, tracking custom attributes, or any other purpose that requires additional data storage. This extensibility allows businesses to adapt the order system to their specific needs without requiring schema changes.
14. Create Physical Product Bundle
Product bundles allow customers to purchase multiple related items as a single unit, often at a discounted price. This use case demonstrates the creation of a physical product bundle where the bundle_details indicate that the items are physically packaged together. The bundle includes information such as whether the item is the base bundle item, images, group identifier, bundle name, item type as physical_bundle, and associated configuration for returns and cancellations. The shipment type is PickAtStore, indicating that the customer will collect the bundle from a physical location. This enables businesses to offer curated product combinations while maintaining proper inventory and fulfillment tracking.
15. Create Virtual Product Bundle - Single Order Single Shipment
Virtual product bundles represent multiple individual items that are sold together but may be sourced or fulfilled separately, even though they are grouped in a single shipment. This use case creates a virtual bundle where all bundle items are included in one order with a single shipment. Each line item contains bundle_details indicating its role in the bundle (base or component), the group identifier linking related bundle items, and the bundle metadata. Unlike physical bundles, virtual bundles allow for more flexible fulfillment as items can be tracked individually while maintaining their bundle relationship. This is useful when items need separate inventory management or when components may have different fulfillment timelines.
16. Create Virtual Product Bundle - Single Order Single Shipment Multiple Line Items
This use case extends the virtual bundle concept to scenarios where a single order contains a single shipment but includes multiple line items that may belong to different bundle groups or represent multiple quantities of bundle components. Each line item maintains its bundle_details with group identifiers that link related items together. This allows for complex bundle configurations where customers might order multiple bundles or additional items alongside bundles, all within a single shipment. The system can track which items belong to which bundle group while processing them together in one fulfillment operation.
17. Create Virtual Product Bundle - Single Order Multiple Shipments
When bundle items need to be fulfilled from different locations or at different times, they can be split across multiple shipments within a single order. This use case demonstrates a virtual product bundle where the bundle components are distributed across multiple shipments, each potentially having different fulfillment timelines, locations, or courier partners. Each shipment contains its subset of bundle items, and all items maintain their bundle_details with group identifiers to preserve the bundle relationship. This enables businesses to optimize fulfillment by shipping items from the most appropriate locations while maintaining the bundle's commercial relationship and allowing for proper tracking and customer communication about partial shipments.