Update Order

Update an existing order.

HTTP Request

PATCH/api/orders/:id

Authorization

Authorization

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

Path Parameters

Parameter	Type	Required	Description
id	Integer	Yes	Unique ID of the order to update

Request Body

Field	Type	Required	Description
status	String	No	Order status (`new`, `hold`, `failed`, `cancelled`, `deleted`)
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	Object	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

Status Options

We have some rules to transition between statuses. Look at the table below:

From \ To	new	hold	failed	cancelled	processing	shipped	completed	refunded	deleted
new		✓	✓	✓					✓
hold			✓	✓	✓	✓	✓		✓
failed		✓		✓	✓	✓	✓	✓	✓
cancelled		✓	✓		✓	✓	✓	✓	✓
processing		✓	✓	✓		✓	✓	✓
shipped		✓	✓	✓	✓		✓
completed		✓	✓	✓	✓	✓		✓	✓
refunded				✓					✓

Transition Rules Diagram

Example Requests

🐍 Python

1import requests
2
3# Partial update (PATCH)
4response = requests.patch('http://www.example.com/api/orders/123', 
5  json={
6      'status': 'hold',
7      'notes': 'Updated delivery instructions',
8      'shipping_cost': 20.00
9  },
10  headers={'Authorization': 'Token <your_api_key>'}
11)
12print(response.json())
13
14# Update billing information
15response = requests.patch('http://www.example.com/api/orders/123', 
16  json={
17      'billing_first_name': 'Jane',
18      'billing_last_name': 'Smith',
19      'billing_address': '456 Oak Avenue'
20  },
21  headers={'Authorization': 'Token <your_api_key>'}
22)
23print(response.json())

🌐 Curl

1# Partial update (PATCH)
2curl -X PATCH "http://www.example.com/api/orders/123" -H "Authorization: Token <your_api_key>" -H "Content-Type: application/json" -d '{
3  "status": "hold",
4  "notes": "Updated delivery instructions",
5  "shipping_cost": 20.00
6}'
7
8# Update billing information
9curl -X PATCH "http://www.example.com/api/orders/123" -H "Authorization: Token <your_api_key>" -H "Content-Type: application/json" -d '{
10  "billing_first_name": "Jane",
11  "billing_last_name": "Smith",
12  "billing_address": "456 Oak Avenue"
13}'

Status Codes

Code	Description
200	Product updated successfully
400	Bad request — invalid input
401	Unauthorized — authentication required
403	Forbidden — insufficient permissions
404	Not found — product does not exist
500	Internal server error

Response Fields

Field	Type	Description
id	Integer	Unique ID of the order
key	String	Unique key of the order (read-only)
status	String	Current status of the order
customer_data	Object	Customer information (read-only)
payment_method_data	Object	Payment method information (read-only)
shipping_method_data	Object	Shipping method information (read-only)
shipping_cost	Number	Cost of shipping
notes	String	Order notes
extra	Object	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 (read-only)
billing_state_data	Object	Billing state information (read-only)
billing_city_data	Object	Billing city information (read-only)
billing_address	String	Billing address
billing_postal_code	String	Billing postal code
billing_national_code	String	Billing national code
billing_mobile_number	String	Billing mobile number
billing_first_name	String	Billing first name
billing_last_name	String	Billing last name
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)

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	Object	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

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

Customer Structure

The customer object contains:

Field	Type	Description
id	Integer	Customer ID
username	String	Customer username
full_name	String	Customer full name (computed)

Geographic Data Structures

Country, state, and city objects contain:

Country/State:

Field	Type	Description
id	Integer	Location ID
active	Boolean	Whether location is active
name	String	Location name
code	String	Location code

City:

Field	Type	Description
id	Integer	City ID
active	Boolean	Whether city is active
name	String	City name