Create Order

Create a new order.

HTTP Request

POST/api/orders/

NOTE: NOT USING THE TRAILING SLASH AT THE END OF THE URL RESULTS TO A 500 SERVER ERROR

Authorization

Authorization

• Required: Yes
• Permission: Staff with OrderPermission or Admin
• Permission Code: 2201
• Authentication: Token-based (Authorization: Token <your_api_key>)

Request Body

Field	Type	Required	Description
status	String	No	Order status (`new`, `hold`, `failed`, `cancelled`, `processing`, `shipped`, `completed`, `refunded`, default=`new`)
customer	Integer	No	Customer ID
payment_method	Integer	No	Payment method ID
shipping_method	Integer	No	Shipping method ID
shipping_cost	Number	No	Cost of shipping
notes	String	No	Order notes
extra	JsonField	No	Additional order data
billing_country	Integer	No	Billing country ID
billing_state	Integer	No	Billing state ID
billing_city	Integer	No	Billing city ID
billing_address	String	No	Billing address
billing_postal_code	String	No	Billing postal code
billing_national_code	String	No	Billing national code
billing_mobile_number	String	No	Billing mobile number
billing_first_name	String	No	Billing first name
billing_last_name	String	No	Billing last name

Example Requests

🐍 Python

1import requests
2
3# Create a new order
4response = requests.post('http://www.example.com/api/orders', 
5  json={
6      'status': 'new',
7      'customer': 123,
8      'payment_method': 1,
9      'shipping_method': 2,
10      'shipping_cost': 75000,
11      'notes': 'Urgent delivery required',
12      'billing_first_name': 'John',
13      'billing_last_name': 'Doe',
14      'billing_address': '123 Main St',
15      'billing_mobile_number': '+1234567890'
16  },
17  headers={'Authorization': 'Token <your_api_key>'}
18)
19print(response.json())
20
21# Create minimal order
22response = requests.post('http://www.example.com/api/orders', 
23  json={
24      'customer': 456,
25      'notes': 'Standard order'
26  },
27  headers={'Authorization': 'Token <your_api_key>'}
28)
29print(response.json())

🌐 Curl

1# Create a new order
2curl -X POST "http://www.example.com/api/orders" -H "Authorization: Token <your_api_key>" -H "Content-Type: application/json" -d '{
3  "status": "pending",
4  "customer": 123,
5  "payment_method": 1,
6  "shipping_method": 2,
7  "shipping_cost": 15.00,
8  "notes": "Urgent delivery required",
9  "billing_first_name": "John",
10  "billing_last_name": "Doe",
11  "billing_address": "123 Main St",
12  "billing_mobile_number": "09305321545"
13}'
14
15# Create minimal order
16curl -X POST "http://www.example.com/api/orders" -H "Authorization: Token <your_api_key>" -H "Content-Type: application/json" -d '{
17  "customer": 456,
18  "notes": "Standard order"
19}'

Response Fields

Field	Type	Description
id	Integer	Unique ID of the order
key	String	Unique key of the order (unique)
status	String	Current status of the order(choices)
customer_data	Object	Customer information (nullable)
payment_method_data	Object	Payment method information (nullable)
shipping_method_data	Object	Shipping method information (nullable)
shipping_cost	Number	Cost of shipping (default=0)
notes	String	Order notes (nullable)
extra	JsonField	Additional order data
created_at	String (ISO 8601)	Timestamp when order was created
updated_at	String (ISO 8601)	Timestamp when order was last updated
billing_country_data	Object	Billing country information (nullable)
billing_state_data	Object	Billing state information (nullable)
billing_city_data	Object	Billing city information (nullable)
billing_address	String	Billing address (nullable)
billing_postal_code	String	Billing postal code (nullable)
billing_national_code	String	Billing national code (nullable)
billing_mobile_number	String	Billing mobile number (nullable, valid iranian mobile number)
billing_first_name	String	Billing first name (nullable)
billing_last_name	String	Billing last name (nullable)
count	Integer	Number of items in order (computed field)
quantity	Integer	Total quantity of items (computed field)
items_subtotal	Number	Subtotal of all items (computed field)
items_discount	Number	Total discount on items (computed field)
subtotal	Number	Order subtotal (computed field)
total_discount	Number	Total discount amount (computed field)
total	Number	Order total amount (computed field)
amount_paid	Number	Amount already paid (computed field)
amount_outstanding	Number	Outstanding amount (computed field)
is_paid	Boolean	Whether order is fully paid (computed field)
items	Array	List of order items (read-only)
payments	Array	List of order payments (read-only)

Customer Structure

The customer object contains:

Field	Type	Description
id	Integer	Customer ID
username	String	Customer username
mobile_number	String	Customer mobile number
first_name	String	Customer first name
last_name	String	Customer last name
full_name	String	Customer full name (computed)

Payment Method Structure

The payment_method object contains:

Field	Type	Description
id	Integer	Payment method ID
name	String	Payment method name
image	Object	Payment method image data

Shipping Method Structure

The shipping_method object contains:

Field	Type	Description
id	Integer	Shipping method ID
name	String	Shipping method name
image	Object	Shipping method image data

Image Data Structure

Field	Type	Description
id	Integer	Unique ID of the image
type	String	File type (e.g., image/jpeg)
name	String	Original file name
size	Integer	File size in bytes
human_readable_size	String	Human readable file size (e.g., 2.5 MB)
f	String	URL to access the image file
width	Integer	Image width in pixels
height	Integer	Image height in pixels
mode	String	Color mode (e.g., RGB, CMYK)
thumbnails	List of thumbnail objects	Imgae thumbnails

Thumbnail Data Structure

Field	Type	Description
id	Integer	Unique ID of the thumbnail (unique)
f	String	URL to access the thumbnail file
size	Integer	File size in bytes (nullable)

Geographic Data Structures

Country, state, and city objects contain:

Country/State:

Field	Type	Description
id	Integer	Location ID
name	String	Location name
code	String	Location code

City:

Field	Type	Description
id	Integer	City ID
name	String	City name

Order Items Structure

Each item in the items array contains:

Field	Type	Description
id	Integer	Unique ID of the order item
product	Integer	Unique ID of the product
product_name	String	Current Product Name
product_data	JsonField	Snapshot of product data at time of order
unit_price	Integer	Price per unit (in smallest currency unit)
unit_discount	Integer	Discount per unit (in smallest currency unit)
quantity	Integer	Quantity ordered
notes	String	Item-specific notes
subtotal	Integer	Calculated subtotal (computed field)
discount	Integer	Total discount for this item (computed field)
total	Integer	Final total for this item (computed field)
created_at	String (ISO 8601)	Item creation timestamp
updated_at	String (ISO 8601)	Item last update timestamp

Order Payment Structure

Each item in the payments array contains:

• The shipping method structure here is the same as the above-mentioned ShippingMethod Structure.

Field	Type	Description
id	Integer	Id of the order payment
payment_method_data	Object	Payment method data of the order payment
approved	Boolean	Whether the order payment is approved
amount	Integer	The order payment amount
transaction_id	String	The transaction id of the order payment
notes	String	The extra notes about the order payment
created_at	String (ISO 8601)	The creation datetime of the order payment
updated_at	String (ISO 8601)	The last updated datetime of the order payment

Example Response

{
    "id": 2,
    "key": "0c86ab758d3e236cb5a4",
    "status": "new",
    "customer_data": {
        "id": 1,
        "username": "BehroozGhorbani",
        "mobile_number": "09308744204",
        "first_name": "بهروز",
        "last_name": "قربانی",
        "full_name": "بهروز قربانی"
    },
    "payment_method_data": {
        "id": 1,
        "name": "پرداخت در مخل",
        "image": null
    },
    "shipping_method_data": {
        "id": 1,
        "name": "پیک موتور",
        "image": {
            "id": 8,
            "type": "image",
            "name": "پیک موتوری",
            "size": 808754,
            "human_readable_size": "789.80 KB",
            "f": "http://127.0.0.1:8000/media/core_media/2025/12/20/Fantasticheskie_kartinki_dlja_monitora_68_63.jpg",
            "width": 1920,
            "height": 1080,
            "mode": "RGB",
            "thumbnails": [
              {
                  "id": 213,
                  "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_64x64.jpg",
                  "size": 64
              },
              {
                  "id": 214,
                  "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_128x128.jpg",
                  "size": 128
              },
              {
                  "id": 215,
                  "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_512x512.jpg",
                  "size": 512
              },
              {
                  "id": 216,
                  "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_1080x1080.jpg",
                  "size": 1080
              }
            ]
        }
    },
    "shipping_cost": 75000,
    "notes": "Facilis sequi alias optio. Alias ipsam deserunt. At veniam nam et. Et aut id id aut quae non animi. Sed tempora aut ut ipsa dicta vel eveniet et aspernatur.",
    "extra": {
        "some": "data"
    },
    "created_at": "2025-12-27T18:17:09.771123Z",
    "updated_at": "2025-12-27T18:17:09.771131Z",
    "billing_country_data": {
        "id": 1,
        "name": "ایران",
        "code": "IR"
    },
    "billing_state_data": {
        "id": 1,
        "name": "آذربایجان شرقی",
        "code": "EA"
    },
    "billing_city_data": {
        "id": 1,
        "name": "اسکو"
    },
    "billing_address": "5411 Stokes Grove",
    "billing_postal_code": "1234567890",
    "billing_national_code": null,
    "billing_mobile_number": "09523296536",
    "billing_first_name": "پدرام",
    "billing_last_name": "زمانی",
    "count": 0,
    "quantity": 0,
    "items_subtotal": 0,
    "items_discount": 0,
    "subtotal": 0,
    "total_discount": 0,
    "total": 75000,
    "amount_paid": 0,
    "amount_outstanding": 75000,
    "is_paid": false,
    "is_payable": false,
    "items": [],
    "payments": []
}

Notes

• The status field can be set to new, hold, failed, cancelled, or deleted when creating an order.
• The status field cannot be set to processing, completed, or refunded and shipped during order creation; these statuses are reserved for later stages in the order lifecycle.