Skip to main content
POST
/
api
/
v2
/
order
Create Order
curl --request POST \
  --url https://api.example.com/api/v2/order \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payment_method": "<string>",
  "order_platform": "<string>",
  "is_pos_order": true,
  "pos_store_id": 123,
  "pos_user_id": 123,
  "purchase_reason_id": 123,
  "is_hyperlocal": true,
  "timeslot": "<string>",
  "store_id": 123,
  "location_id": 123,
  "is_abandon_cart_order": true,
  "shipments": [
    {}
  ],
  "additional_info": {}
}
'
{
  "order": 123,
  "method": 123,
  "isValid": true,
  "name": "<string>",
  "title": "<string>",
  "description": "<string>"
}

​
Overview

The order creation endpoint processes cart items and creates a new order. This endpoint handles product orders, gift vouchers, payment processing, and inventory allocation.

​
Authentication

This endpoint requires user authentication via the auth_required decorator.
​
Authorization
string
required
Bearer token for authenticated user session

​
Request Body

​
payment_method
string
required
Payment method for the order. Supported values:
  • cod - Cash on Delivery
  • upi - UPI payment
  • prepaid - Other prepaid methods
​
order_platform
string
default:"MOBILE"
Platform where order is placed. Must be one of: MOBILE, WEB, POS
​
is_pos_order
boolean
Whether this is a Point of Sale order
​
pos_store_id
integer
Store ID if placing order through POS
​
pos_user_id
integer
User ID of POS operator
​
purchase_reason_id
integer
Reason code for purchase (used for store accounts)
​
is_hyperlocal
boolean
Whether this is a same-day hyperlocal delivery order
​
timeslot
string
Delivery timeslot for hyperlocal orders
​
store_id
integer
Store ID for hyperlocal fulfillment
​
location_id
integer
Location ID for hyperlocal delivery
​
is_abandon_cart_order
boolean
Flag to track if order was created from abandoned cart recovery
​
shipments
array
Array of shipment objects for split delivery orders. Each shipment contains:
  • standard - Standard delivery items
  • same_day - Same day delivery items
  • hyperlocal - Hyperlocal delivery items
​
boolean
Save UPI details for future use (query parameter)
​
additional_info
object
Additional payment information:
  • value - UPI VPA for UPI payments

​
Order Creation Flow

  1. Validation Phase
    • Validates user authentication and cart contents
    • Checks COD eligibility based on pincode, cart value, and user history
    • Validates product stock availability
    • Ensures address details are complete
  2. COD Restrictions
    • Gift vouchers: COD not allowed
    • Product-specific: Some products don’t support COD
    • Amount limits: Min ₹, Max ₹
    • Location: COD availability varies by pincode
    • Hyperlocal orders: COD not supported for same-day delivery
    • RTO history: COD may be disabled for users with multiple RTO orders
  3. Order Processing
    • Creates order record with unique order reference number
    • Allocates products from inventory
    • Processes exclusive membership if applicable
    • Creates has_products records for each line item
    • Applies TSS Money, TSS Points, and gift vouchers
    • Assigns warehouse for fulfillment
  4. Special Handling
    • Mystery Products: Reveals actual product during order creation
    • Bundle Products: Creates separate line items for bundle components
    • Complementary Products: Adds free products if eligible
    • Welcome Note: First-time buyers receive welcome product
    • Freebie Sale: Limited quantity freebies for eligible orders

​
Response

​
order
integer
The unique order ID
​
method
integer
Payment method code:
  • 0 - Prepaid
  • 1 - Cash on Delivery
  • 3 - TSS Money
​
isValid
boolean
Whether the order was successfully created
​
name
string
Response identifier: placed_order

​
Order Reference Number Format

Order reference numbers are generated based on platform:
  • MOBILE: M{order_id}
  • WEB: W{order_id}
  • POS: P{order_id}

​
Error Responses

​
title
string
Error title
​
description
string
Detailed error message

​
Common Errors

  • Please select an address - No delivery address provided
  • Enter phone number - Phone number missing in address
  • Can not deliver to given address - Invalid country (only India supported)
  • Some products are out of stock - Insufficient inventory
  • COD is not applicable - COD validation failed
  • Something went wrong, please try again - Order creation failed
  • Please select at least one product to place the order - Empty cart
  • Single quantity of Microsoft Azure product can be purchased - Quantity restriction
  • Single Nestle products can be purchased at a time - Product restriction
  • This slot is not available - Hyperlocal timeslot unavailable

​
Example Request

{
  "payment_method": "upi",
  "order_platform": "MOBILE",
  "additional_info": {
    "value": "user@paytm"
  },
  "os": "android",
  "version": "4.5.0"
}

​
Example Response

{
  "order": 123456,
  "method": 0,
  "isValid": true,
  "name": "placed_order"
}

​
Post-Order Processing

After successful order creation:
  1. Warehouse assignment task is queued
  2. Cart is persisted with order details
  3. Exclusive membership activated if purchased
  4. Refund amounts calculated for each product
  5. Cashback points allocated
  6. Inventory locked for the order
  7. Lifetime savings cache invalidated

​
Notes

  • Orders placed with TSS Money/Points create transaction locks to prevent duplicate orders
  • Transaction lock expires after configured timeout (TXN_LOCK_EXPIRY)
  • Hyperlocal orders automatically assign Borzo India courier (ID: 13)
  • Split delivery orders can have multiple shipment types in single order
  • Mystery products are resolved to actual products during order creation
  • First-time buyers automatically receive welcome note product

Build docs developers (and LLMs) love

Get started for freeTalk to us