List All Orders

Retrieves a list of all orders with optional filtering, sorting, and pagination.

HTTP Request

GET/api/orders

NOTE: NOT USING THE TRAILING SLASH AT THE END OF THE URL RESULTS TO AN EXTRA REDIRECT WITH 301 STATUS

Authorization

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

Query Parameters

Parameter	Type	Default	Description
limit	integer	10	Number of results to return per page
offset	integer	0	Number of results to skip before returning results
search	string		Search term to lookup results by`id`, `key`, `customer__id`, `customer__first_name`, `customer__last_name`, `customer__email`, `customer__username`, `customer__mobile_number`, `notes`, `billing_country__name`, `billing_state__name`, `billing_city__name`, `billing_first_name`, `billing_last_name`, `billing_mobile_number`
ordering	string	-created_at	Order results by (`id`, `status`, `customer__id`, `customer__username`, `customer__first_name`, `customer__last_name`, `shipping_cost`, `created_at`, `updated_at`)
status	string		Filter by specific order status (`new`, `hold`, `failed`, `cancelled`, `processing`, `shipped`, `completed`, `refunded`, `deleted`)
status_in	string		Filter by multiple order statuses (comma-separated)
payment_method	integer		Filter by specific payment method ID
payment_method_in	string		Filter by multiple payment method IDs (comma-separated)
shipping_method	integer		Filter by specific shipping method ID
shipping_method_in	string		Filter by multiple shipping method IDs (comma-separated)
billing_country	integer		Filter by billing country ID
billing_state	integer		Filter by billing state ID
billing_city	integer		Filter by billing city ID
billing_country_in	string		Filter by multiple billing country IDs (comma-separated)
billing_state_in	string		Filter by multiple billing state IDs (comma-separated)
billing_city_in	string		Filter by multiple billing city IDs (comma-separated)
has_notes	boolean		Filter orders with/without notes
customer	integer		Filter by specific customer ID
customer_in	string		Filter by multiple customer IDs (comma-separated)
shipping_cost_min	number		Minimum shipping cost filter
shipping_cost_max	number		Maximum shipping cost filter
has_customer	boolean		Filter orders with/without customer
has_payment_method	boolean		Filter orders with/without payment method
has_shipping_method	boolean		Filter orders with/without shipping method
has_billing_country	boolean		Filter orders with/without billing country
has_billing_state	boolean		Filter orders with/without billing state
has_billing_city	boolean		Filter orders with/without billing city
has_billing_address	boolean		Filter orders with/without billing address
has_billing_postal_code	boolean		Filter orders with/without billing postal code
has_billing_national_code	boolean		Filter orders with/without billing national code
has_billing_mobile_number	boolean		Filter orders with/without billing mobile number
has_billing_first_name	boolean		Filter orders with/without billing first name
has_billing_last_name	boolean		Filter orders with/without billing last name
id_min	integer		Minimum ID filter
id_max	integer		Maximum ID filter
created_date	string		Filter by creation date (e.g., 2023-01-01)
updated_date	string		Filter by last updated date (e.g., 2023-01-01)
created_from	string		Filter by creation date range start
created_to	string		Filter by creation date range end
updated_from	string		Filter by last updated date range start
updated_to	string		Filter by last updated date range end

Example Requests

🐍 Python
🌐 Curl

1import requests
2
3# List all orders
4response = requests.get('http://www.example.com/api/orders', 
5  headers={'Authorization': 'Token <your_api_key>'}
6)
7print(response.json())
8
9# Search for orders with filters
10response = requests.get('http://www.example.com/api/orders', params={
11  'search': 'john',
12  'status': 'pending',
13  'has_customer': True,
14  'ordering': '-created_at',
15  'limit': 20
16}, headers={'Authorization': 'Token <your_api_key>'})
17print(response.json())
18
19# Filter by customer and payment method
20response = requests.get('http://www.example.com/api/orders', params={
21  'customer': 123,
22  'payment_method': 1,
23  'shipping_cost_min': 10.00
24}, headers={'Authorization': 'Token <your_api_key>'})
25print(response.json())

1# List all orders
2curl "http://www.example.com/api/orders" -H "Authorization: Token <your_api_key>"
3
4# Search with filters
5curl "http://www.example.com/api/orders?search=john&status=pending&has_customer=true&ordering=-created_at&limit=20" -H "Authorization: Token <your_api_key>"
6
7# Filter by customer and payment method
8curl "http://www.example.com/api/orders?customer=123&payment_method=1&shipping_cost_min=10.00" -H "Authorization: Token <your_api_key>"

Response Fields

Field	Type	Description
count	Integer	Total number of categories
next	String	URL for the next page of results
previous	String	URL for the previous page of results
results	Array[Object]	Array of Order objects

Order Object Data Structure

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

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 2,
            "key": "0c86ab758d3e236cb5a4",
            "status": "processing",
            "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-28T10:43:38.505960Z",
            "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": 2,
            "quantity": 15,
            "items_subtotal": 52300000,
            "items_discount": 3300000,
            "subtotal": 52300000,
            "total_discount": 3300000,
            "total": 49075000,
            "amount_paid": 500000,
            "amount_outstanding": 48575000,
            "is_paid": false,
            "is_payable": true,
            "items": [
                {
                    "id": 1,
                    "product": 36,
                    "product_title": "ماوس لاجیتک MX Vertical",
                    "product_data": {},
                    "unit_price": 8500000,
                    "unit_discount": 500000,
                    "quantity": 5,
                    "notes": "handle with care",
                    "subtotal": 42500000,
                    "discount": 2500000,
                    "total": 40000000,
                    "created_at": "2025-12-28T10:43:38.506842Z",
                    "updated_at": "2025-12-28T10:43:38.506846Z"
                },
                {
                    "id": 2,
                    "product": 53,
                    "product_title": "آلاینده هوا پرایدی",
                    "product_data": {
                        "key": "value"
                    },
                    "unit_price": 980000,
                    "unit_discount": 80000,
                    "quantity": 10,
                    "notes": "",
                    "subtotal": 9800000,
                    "discount": 800000,
                    "total": 9000000,
                    "created_at": "2025-12-28T10:43:38.508594Z",
                    "updated_at": "2025-12-28T10:43:38.508598Z"
                }
            ],
            "payments": [
                {
                    "id": 1,
                    "payment_method_data": {
                        "id": 1,
                        "name": "پرداخت در مخل",
                        "image": null
                    },
                    "approved": true,
                    "amount": 500000,
                    "transaction_id": "1589800",
                    "notes": "",
                    "created_at": "2025-12-28T10:43:38.509103Z",
                    "updated_at": "2025-12-28T10:43:38.509107Z"
                }
            ]
        },
        {
            "id": 1,
            "key": "3ecb7a870edb5da998f6",
            "status": "new",
            "customer_data": null,
            "payment_method_data": null,
            "shipping_method_data": null,
            "shipping_cost": 0,
            "notes": null,
            "extra": {},
            "created_at": "2025-12-27T18:12:18.461023Z",
            "updated_at": "2025-12-27T18:12:18.461032Z",
            "billing_country_data": null,
            "billing_state_data": null,
            "billing_city_data": null,
            "billing_address": null,
            "billing_postal_code": null,
            "billing_national_code": null,
            "billing_mobile_number": null,
            "billing_first_name": null,
            "billing_last_name": null,
            "count": 0,
            "quantity": 0,
            "items_subtotal": 0,
            "items_discount": 0,
            "subtotal": 0,
            "total_discount": 0,
            "total": 0,
            "amount_paid": 0,
            "amount_outstanding": 0,
            "is_paid": false,
            "is_payable": false,
            "items": [],
            "payments": []
        }
    ]
}

Notes

Valid status choices are: new, hold, failed, cancelled, processing, shipped, completed, refunded

HTTP Request​

Authorization​

Authorization

Query Parameters​

Example Requests​

Response Fields​

Customer Structure​

Payment Method Structure​

Shipping Method Structure​

Geographic Data Structures​

Order Items Structure​

Order Payment Structure​

Example Response​

Notes​

HTTP Request

Authorization

Query Parameters

Example Requests

Response Fields

Customer Structure

Payment Method Structure

Shipping Method Structure

Geographic Data Structures

Order Items Structure

Order Payment Structure

Example Response

Notes