> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/woocommerce/woocommerce/llms.txt
> Use this file to discover all available pages before exploring further.
# Orders REST API
> Manage orders through the WooCommerce REST API - list, create, update, and delete orders
# Orders API
The Orders endpoint allows you to create, read, update, and delete orders in your WooCommerce store.
## The Order Object
### Order Properties
Unique identifier for the order. Read-only.
Parent order ID.
Order number. Read-only.
Order key. Read-only.
How the order was created: `checkout`, `rest-api`, `admin`
Order status. Options: `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded`, `failed`, `trash`
Currency the order was created with, in ISO 4217 format.
The date the order was created, in ISO8601 format. Read-only.
The date the order was last modified, in ISO8601 format. Read-only.
Total discount amount for the order. Read-only.
Total discount tax amount for the order. Read-only.
Total shipping amount for the order. Read-only.
Total shipping tax amount for the order. Read-only.
Sum of line item taxes only. Read-only.
Grand total. Read-only.
Sum of all taxes. Read-only.
User ID who owns the order. 0 for guests.
Billing address.
```json theme={null}
{
"first_name": "John",
"last_name": "Doe",
"company": "",
"address_1": "123 Main St",
"address_2": "Apt 4",
"city": "New York",
"state": "NY",
"postcode": "10001",
"country": "US",
"email": "john@example.com",
"phone": "555-1234"
}
```
Shipping address.
```json theme={null}
{
"first_name": "John",
"last_name": "Doe",
"company": "",
"address_1": "123 Main St",
"address_2": "Apt 4",
"city": "New York",
"state": "NY",
"postcode": "10001",
"country": "US"
}
```
Payment method ID.
Payment method title.
Unique transaction ID from payment gateway.
Line items data.
```json theme={null}
[
{
"id": 789,
"name": "Premium T-Shirt",
"product_id": 123,
"quantity": 2,
"subtotal": "49.98",
"total": "49.98"
}
]
```
## List All Orders
Retrieve a list of all orders in your store.
```bash cURL theme={null}
curl https://example.com/wp-json/wc/v3/orders \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
```javascript JavaScript theme={null}
const response = await api.get('/orders');
console.log(response.data);
```
```python Python theme={null}
response = requests.get(
'https://example.com/wp-json/wc/v3/orders',
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
orders = response.json()
```
```php PHP theme={null}
$orders = $woocommerce->get('orders');
```
### Query Parameters
Current page of the collection.
Maximum number of items to return (max 100).
Limit results to those matching a string.
Limit response to orders published after a given ISO8601 date.
Limit response to orders published before a given ISO8601 date.
Limit result set to orders with specific status. Options: `any`, `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded`, `failed`, `trash`
Limit result set to orders assigned to a specific customer (ID).
Limit result set to orders that include a specific product (ID).
Sort collection by attribute. Options: `date`, `id`, `title`, `slug`
Order sort direction. Options: `asc`, `desc`
### Example Response
```json theme={null}
[
{
"id": 456,
"parent_id": 0,
"number": "456",
"order_key": "wc_order_abc123def456",
"created_via": "checkout",
"version": "8.5.0",
"status": "processing",
"currency": "USD",
"date_created": "2024-02-15T14:30:00",
"date_created_gmt": "2024-02-15T19:30:00",
"date_modified": "2024-02-15T14:35:00",
"date_modified_gmt": "2024-02-15T19:35:00",
"discount_total": "5.00",
"discount_tax": "0.00",
"shipping_total": "10.00",
"shipping_tax": "0.80",
"cart_tax": "4.00",
"total": "69.80",
"total_tax": "4.80",
"prices_include_tax": false,
"customer_id": 789,
"customer_ip_address": "192.168.1.1",
"customer_user_agent": "Mozilla/5.0...",
"customer_note": "Please deliver after 5pm",
"billing": {
"first_name": "John",
"last_name": "Doe",
"company": "Acme Inc",
"address_1": "123 Main Street",
"address_2": "Suite 100",
"city": "New York",
"state": "NY",
"postcode": "10001",
"country": "US",
"email": "john.doe@example.com",
"phone": "(555) 123-4567"
},
"shipping": {
"first_name": "John",
"last_name": "Doe",
"company": "Acme Inc",
"address_1": "123 Main Street",
"address_2": "Suite 100",
"city": "New York",
"state": "NY",
"postcode": "10001",
"country": "US"
},
"payment_method": "stripe",
"payment_method_title": "Credit Card (Stripe)",
"transaction_id": "ch_1AbCdEfGhIjKlMnO",
"date_paid": "2024-02-15T14:35:00",
"date_paid_gmt": "2024-02-15T19:35:00",
"date_completed": null,
"date_completed_gmt": null,
"cart_hash": "abc123def456",
"meta_data": [],
"line_items": [
{
"id": 789,
"name": "Premium T-Shirt",
"product_id": 123,
"variation_id": 0,
"quantity": 2,
"tax_class": "",
"subtotal": "49.98",
"subtotal_tax": "4.00",
"total": "49.98",
"total_tax": "4.00",
"taxes": [],
"meta_data": [],
"sku": "TSHIRT-001",
"price": 24.99
}
],
"tax_lines": [],
"shipping_lines": [
{
"id": 234,
"method_title": "Standard Shipping",
"method_id": "flat_rate",
"total": "10.00",
"total_tax": "0.80",
"taxes": []
}
],
"fee_lines": [],
"coupon_lines": [
{
"id": 567,
"code": "SAVE5",
"discount": "5.00",
"discount_tax": "0.00"
}
],
"refunds": []
}
]
```
## Retrieve an Order
Get details of a single order by ID.
```bash cURL theme={null}
curl https://example.com/wp-json/wc/v3/orders/456 \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
```javascript JavaScript theme={null}
const response = await api.get('/orders/456');
console.log(response.data);
```
```python Python theme={null}
response = requests.get(
'https://example.com/wp-json/wc/v3/orders/456',
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
order = response.json()
```
```php PHP theme={null}
$order = $woocommerce->get('orders/456');
```
## Create an Order
Create a new order in your store.
```bash cURL theme={null}
curl -X POST https://example.com/wp-json/wc/v3/orders \
-u ck_1234567890abcdef:cs_1234567890abcdef \
-H "Content-Type: application/json" \
-d '{
"payment_method": "bacs",
"payment_method_title": "Direct Bank Transfer",
"set_paid": true,
"billing": {
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Main Street",
"address_2": "",
"city": "New York",
"state": "NY",
"postcode": "10001",
"country": "US",
"email": "john.doe@example.com",
"phone": "(555) 123-4567"
},
"shipping": {
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Main Street",
"address_2": "",
"city": "New York",
"state": "NY",
"postcode": "10001",
"country": "US"
},
"line_items": [
{
"product_id": 123,
"quantity": 2
},
{
"product_id": 456,
"quantity": 1
}
],
"shipping_lines": [
{
"method_id": "flat_rate",
"method_title": "Flat Rate",
"total": "10.00"
}
]
}'
```
```javascript JavaScript theme={null}
const newOrder = {
payment_method: 'bacs',
payment_method_title: 'Direct Bank Transfer',
set_paid: true,
billing: {
first_name: 'John',
last_name: 'Doe',
address_1: '123 Main Street',
city: 'New York',
state: 'NY',
postcode: '10001',
country: 'US',
email: 'john.doe@example.com',
phone: '(555) 123-4567'
},
shipping: {
first_name: 'John',
last_name: 'Doe',
address_1: '123 Main Street',
city: 'New York',
state: 'NY',
postcode: '10001',
country: 'US'
},
line_items: [
{
product_id: 123,
quantity: 2
}
],
shipping_lines: [
{
method_id: 'flat_rate',
method_title: 'Flat Rate',
total: '10.00'
}
]
};
const response = await api.post('/orders', newOrder);
console.log(response.data);
```
```python Python theme={null}
data = {
'payment_method': 'bacs',
'payment_method_title': 'Direct Bank Transfer',
'set_paid': True,
'billing': {
'first_name': 'John',
'last_name': 'Doe',
'address_1': '123 Main Street',
'city': 'New York',
'state': 'NY',
'postcode': '10001',
'country': 'US',
'email': 'john.doe@example.com',
'phone': '(555) 123-4567'
},
'line_items': [
{
'product_id': 123,
'quantity': 2
}
],
'shipping_lines': [
{
'method_id': 'flat_rate',
'method_title': 'Flat Rate',
'total': '10.00'
}
]
}
response = requests.post(
'https://example.com/wp-json/wc/v3/orders',
json=data,
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
order = response.json()
```
```php PHP theme={null}
$data = [
'payment_method' => 'bacs',
'payment_method_title' => 'Direct Bank Transfer',
'set_paid' => true,
'billing' => [
'first_name' => 'John',
'last_name' => 'Doe',
'address_1' => '123 Main Street',
'city' => 'New York',
'state' => 'NY',
'postcode' => '10001',
'country' => 'US',
'email' => 'john.doe@example.com',
'phone' => '(555) 123-4567'
],
'line_items' => [
[
'product_id' => 123,
'quantity' => 2
]
],
'shipping_lines' => [
[
'method_id' => 'flat_rate',
'method_title' => 'Flat Rate',
'total' => '10.00'
]
]
];
$order = $woocommerce->post('orders', $data);
```
### Required Fields
While no fields are strictly required, you should typically include billing information and at least one line item.
### Important Fields
Billing address object (see Order Object above)
Shipping address object (see Order Object above)
Array of line item objects
```json theme={null}
[{"product_id": 123, "quantity": 2}]
```
Array of shipping line objects
```json theme={null}
[{"method_id": "flat_rate", "method_title": "Flat Rate", "total": "10.00"}]
```
Array of coupon line objects
```json theme={null}
[{"code": "SAVE10"}]
```
User ID. Set to 0 for guest checkout.
Order status: `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded`, `failed`
Set to true to mark order as paid.
## Update an Order
Update an existing order.
```bash cURL theme={null}
curl -X PUT https://example.com/wp-json/wc/v3/orders/456 \
-u ck_1234567890abcdef:cs_1234567890abcdef \
-H "Content-Type: application/json" \
-d '{
"status": "completed"
}'
```
```javascript JavaScript theme={null}
const updates = {
status: 'completed'
};
const response = await api.put('/orders/456', updates);
console.log(response.data);
```
```python Python theme={null}
data = {
'status': 'completed'
}
response = requests.put(
'https://example.com/wp-json/wc/v3/orders/456',
json=data,
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
order = response.json()
```
```php PHP theme={null}
$data = [
'status' => 'completed'
];
$order = $woocommerce->put('orders/456', $data);
```
## Delete an Order
Delete an order permanently or move it to trash.
```bash cURL (Move to Trash) theme={null}
curl -X DELETE https://example.com/wp-json/wc/v3/orders/456 \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
```bash cURL (Permanent Delete) theme={null}
curl -X DELETE https://example.com/wp-json/wc/v3/orders/456?force=true \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
```javascript JavaScript theme={null}
// Move to trash
await api.delete('/orders/456');
// Permanent delete
await api.delete('/orders/456', { params: { force: true } });
```
```python Python theme={null}
# Move to trash
requests.delete(
'https://example.com/wp-json/wc/v3/orders/456',
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
# Permanent delete
requests.delete(
'https://example.com/wp-json/wc/v3/orders/456',
params={'force': True},
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
```
```php PHP theme={null}
// Move to trash
$woocommerce->delete('orders/456');
// Permanent delete
$woocommerce->delete('orders/456', ['force' => true]);
```
## Batch Update Orders
Create, update, and delete multiple orders in a single request.
```bash theme={null}
curl -X POST https://example.com/wp-json/wc/v3/orders/batch \
-u ck_1234567890abcdef:cs_1234567890abcdef \
-H "Content-Type: application/json" \
-d '{
"update": [
{
"id": 456,
"status": "completed"
},
{
"id": 789,
"status": "processing"
}
]
}'
```
## Order Notes
Manage notes attached to orders.
### List Order Notes
```bash theme={null}
curl https://example.com/wp-json/wc/v3/orders/456/notes \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
### Create Order Note
```bash theme={null}
curl -X POST https://example.com/wp-json/wc/v3/orders/456/notes \
-u ck_1234567890abcdef:cs_1234567890abcdef \
-H "Content-Type: application/json" \
-d '{
"note": "Order has been shipped via FedEx",
"customer_note": true
}'
```
## Common Use Cases
### Get Orders by Status
```bash theme={null}
curl "https://example.com/wp-json/wc/v3/orders?status=processing" \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
### Get Customer's Orders
```bash theme={null}
curl "https://example.com/wp-json/wc/v3/orders?customer=789" \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
### Get Orders by Date Range
```bash theme={null}
curl "https://example.com/wp-json/wc/v3/orders?after=2024-01-01T00:00:00&before=2024-12-31T23:59:59" \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
### Mark Order as Completed
```javascript theme={null}
await api.put('/orders/456', {
status: 'completed'
});
```
### Add Tracking Information
```javascript theme={null}
await api.post('/orders/456/notes', {
note: 'Tracking number: 1Z999AA10123456784',
customer_note: true
});
```
## Error Handling
### Invalid Order ID
```json theme={null}
{
"code": "woocommerce_rest_shop_order_invalid_id",
"message": "Invalid order ID.",
"data": {
"status": 404
}
}
```
### Invalid Product in Line Item
```json theme={null}
{
"code": "woocommerce_rest_invalid_product_id",
"message": "Invalid product ID.",
"data": {
"status": 400
}
}
```
### Insufficient Stock
```json theme={null}
{
"code": "woocommerce_rest_product_not_enough_stock",
"message": "Not enough stock available.",
"data": {
"status": 400
}
}
```
## Next Steps
Manage store products
Work with customer data
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.