> ## 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.
# Products REST API
> Manage products through the WooCommerce REST API - list, create, update, and delete products
# Products API
The Products endpoint allows you to create, read, update, and delete products in your WooCommerce store.
## The Product Object
### Product Properties
Unique identifier for the product. Read-only.
Product name.
Product slug. Auto-generated from name if not provided.
Product URL. Read-only.
The date the product was created, in ISO8601 format. Read-only.
The date the product was last modified, in ISO8601 format. Read-only.
Product type. Options: `simple`, `grouped`, `external`, `variable`
Product status. Options: `draft`, `pending`, `private`, `publish`
Featured product.
Catalog visibility. Options: `visible`, `catalog`, `search`, `hidden`
Product description (HTML).
Product short description (HTML).
Unique product identifier (Stock Keeping Unit).
Current product price. Read-only.
Product regular price.
Product sale price.
Whether the product is on sale. Read-only.
Stock status. Options: `instock`, `outofstock`, `onbackorder`
Stock quantity. Only applicable if managing stock.
Enable stock management at product level.
List of product categories.
```json theme={null}
[
{
"id": 15,
"name": "Clothing",
"slug": "clothing"
}
]
```
List of product images.
```json theme={null}
[
{
"id": 456,
"src": "https://example.com/image.jpg",
"name": "Product Image",
"alt": "Product photo"
}
]
```
## List All Products
Retrieve a list of all products in your store.
```bash cURL theme={null}
curl https://example.com/wp-json/wc/v3/products \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
```javascript JavaScript theme={null}
const response = await api.get('/products');
console.log(response.data);
```
```python Python theme={null}
response = requests.get(
'https://example.com/wp-json/wc/v3/products',
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
products = response.json()
```
```php PHP theme={null}
$products = $woocommerce->get('products');
```
### 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 products published after a given ISO8601 date.
Limit response to products published before a given ISO8601 date.
Limit result set to products with specific status. Options: `any`, `draft`, `pending`, `private`, `publish`
Limit result set to products with specific type. Options: `simple`, `grouped`, `external`, `variable`
Limit result set to products with a specific SKU.
Limit result set to featured products.
Limit result set to products in specific category ID(s). Comma-separated list.
Limit result set to products with specific tag ID(s). Comma-separated list.
Limit result set to products on sale.
Limit result set to products based on minimum price.
Limit result set to products based on maximum price.
Limit result set to products with specified stock status. Options: `instock`, `outofstock`, `onbackorder`
Sort collection by attribute. Options: `date`, `id`, `title`, `slug`, `price`, `popularity`, `rating`
Order sort direction. Options: `asc`, `desc`
### Example Response
```json theme={null}
[
{
"id": 123,
"name": "Premium T-Shirt",
"slug": "premium-t-shirt",
"permalink": "https://example.com/product/premium-t-shirt/",
"date_created": "2024-01-15T10:30:00",
"date_modified": "2024-01-20T14:45:00",
"type": "simple",
"status": "publish",
"featured": false,
"catalog_visibility": "visible",
"description": "High-quality cotton t-shirt
",
"short_description": "Comfortable premium t-shirt
",
"sku": "TSHIRT-001",
"price": "24.99",
"regular_price": "29.99",
"sale_price": "24.99",
"on_sale": true,
"purchasable": true,
"total_sales": 45,
"virtual": false,
"downloadable": false,
"downloads": [],
"download_limit": -1,
"download_expiry": -1,
"tax_status": "taxable",
"tax_class": "",
"manage_stock": true,
"stock_quantity": 50,
"stock_status": "instock",
"backorders": "no",
"backorders_allowed": false,
"backordered": false,
"sold_individually": false,
"weight": "0.5",
"dimensions": {
"length": "20",
"width": "15",
"height": "2"
},
"shipping_required": true,
"shipping_taxable": true,
"shipping_class": "",
"shipping_class_id": 0,
"reviews_allowed": true,
"average_rating": "4.5",
"rating_count": 12,
"categories": [
{
"id": 15,
"name": "Clothing",
"slug": "clothing"
}
],
"tags": [
{
"id": 23,
"name": "Summer",
"slug": "summer"
}
],
"images": [
{
"id": 456,
"date_created": "2024-01-15T10:30:00",
"date_modified": "2024-01-15T10:30:00",
"src": "https://example.com/wp-content/uploads/2024/01/tshirt.jpg",
"name": "tshirt.jpg",
"alt": "Premium T-Shirt"
}
],
"attributes": [],
"default_attributes": [],
"variations": [],
"grouped_products": [],
"menu_order": 0,
"meta_data": []
}
]
```
## Retrieve a Product
Get details of a single product by ID.
```bash cURL theme={null}
curl https://example.com/wp-json/wc/v3/products/123 \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
```javascript JavaScript theme={null}
const response = await api.get('/products/123');
console.log(response.data);
```
```python Python theme={null}
response = requests.get(
'https://example.com/wp-json/wc/v3/products/123',
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
product = response.json()
```
```php PHP theme={null}
$product = $woocommerce->get('products/123');
```
## Create a Product
Create a new product in your store.
```bash cURL theme={null}
curl -X POST https://example.com/wp-json/wc/v3/products \
-u ck_1234567890abcdef:cs_1234567890abcdef \
-H "Content-Type: application/json" \
-d '{
"name": "Premium Hoodie",
"type": "simple",
"regular_price": "49.99",
"description": "Comfortable premium hoodie made from organic cotton.",
"short_description": "Premium organic cotton hoodie",
"categories": [
{
"id": 15
}
],
"images": [
{
"src": "https://example.com/images/hoodie.jpg"
}
]
}'
```
```javascript JavaScript theme={null}
const newProduct = {
name: 'Premium Hoodie',
type: 'simple',
regular_price: '49.99',
description: 'Comfortable premium hoodie made from organic cotton.',
short_description: 'Premium organic cotton hoodie',
categories: [
{ id: 15 }
],
images: [
{ src: 'https://example.com/images/hoodie.jpg' }
]
};
const response = await api.post('/products', newProduct);
console.log(response.data);
```
```python Python theme={null}
data = {
'name': 'Premium Hoodie',
'type': 'simple',
'regular_price': '49.99',
'description': 'Comfortable premium hoodie made from organic cotton.',
'short_description': 'Premium organic cotton hoodie',
'categories': [{'id': 15}],
'images': [{'src': 'https://example.com/images/hoodie.jpg'}]
}
response = requests.post(
'https://example.com/wp-json/wc/v3/products',
json=data,
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
product = response.json()
```
```php PHP theme={null}
$data = [
'name' => 'Premium Hoodie',
'type' => 'simple',
'regular_price' => '49.99',
'description' => 'Comfortable premium hoodie made from organic cotton.',
'short_description' => 'Premium organic cotton hoodie',
'categories' => [
['id' => 15]
],
'images' => [
['src' => 'https://example.com/images/hoodie.jpg']
]
];
$product = $woocommerce->post('products', $data);
```
### Required Fields
Product name
### Optional Fields
Product type: `simple`, `grouped`, `external`, `variable`
Product regular price
Product sale price
Product description (supports HTML)
Product short description (supports HTML)
Unique SKU (Stock Keeping Unit)
Enable stock management
Stock quantity (requires `manage_stock` to be true)
Stock status: `instock`, `outofstock`, `onbackorder`
List of category IDs
```json theme={null}
[{"id": 15}, {"id": 23}]
```
List of product images
```json theme={null}
[{"src": "https://example.com/image.jpg"}]
```
## Update a Product
Update an existing product.
```bash cURL theme={null}
curl -X PUT https://example.com/wp-json/wc/v3/products/123 \
-u ck_1234567890abcdef:cs_1234567890abcdef \
-H "Content-Type: application/json" \
-d '{
"regular_price": "54.99",
"sale_price": "44.99"
}'
```
```javascript JavaScript theme={null}
const updates = {
regular_price: '54.99',
sale_price: '44.99'
};
const response = await api.put('/products/123', updates);
console.log(response.data);
```
```python Python theme={null}
data = {
'regular_price': '54.99',
'sale_price': '44.99'
}
response = requests.put(
'https://example.com/wp-json/wc/v3/products/123',
json=data,
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
product = response.json()
```
```php PHP theme={null}
$data = [
'regular_price' => '54.99',
'sale_price' => '44.99'
];
$product = $woocommerce->put('products/123', $data);
```
## Delete a Product
Delete a product permanently or move it to trash.
```bash cURL (Move to Trash) theme={null}
curl -X DELETE https://example.com/wp-json/wc/v3/products/123 \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
```bash cURL (Permanent Delete) theme={null}
curl -X DELETE https://example.com/wp-json/wc/v3/products/123?force=true \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
```javascript JavaScript theme={null}
// Move to trash
await api.delete('/products/123');
// Permanent delete
await api.delete('/products/123', { params: { force: true } });
```
```python Python theme={null}
# Move to trash
requests.delete(
'https://example.com/wp-json/wc/v3/products/123',
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
# Permanent delete
requests.delete(
'https://example.com/wp-json/wc/v3/products/123',
params={'force': True},
auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
```
```php PHP theme={null}
// Move to trash
$woocommerce->delete('products/123');
// Permanent delete
$woocommerce->delete('products/123', ['force' => true]);
```
### Parameters
Set to `true` to permanently delete the product. Otherwise, it will be moved to trash.
## Batch Update Products
Create, update, and delete multiple products in a single request.
```bash theme={null}
curl -X POST https://example.com/wp-json/wc/v3/products/batch \
-u ck_1234567890abcdef:cs_1234567890abcdef \
-H "Content-Type: application/json" \
-d '{
"create": [
{
"name": "Product 1",
"type": "simple",
"regular_price": "10.00"
},
{
"name": "Product 2",
"type": "simple",
"regular_price": "20.00"
}
],
"update": [
{
"id": 123,
"regular_price": "15.00"
}
],
"delete": [
456
]
}'
```
## Product Variations
For variable products, you can manage variations through a sub-endpoint.
### List Product Variations
```bash theme={null}
curl https://example.com/wp-json/wc/v3/products/123/variations \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
### Create a Variation
```bash theme={null}
curl -X POST https://example.com/wp-json/wc/v3/products/123/variations \
-u ck_1234567890abcdef:cs_1234567890abcdef \
-H "Content-Type: application/json" \
-d '{
"regular_price": "19.99",
"attributes": [
{
"id": 1,
"option": "Large"
}
]
}'
```
## Common Use Cases
### Update Stock Quantity
```javascript theme={null}
await api.put('/products/123', {
manage_stock: true,
stock_quantity: 100,
stock_status: 'instock'
});
```
### Set Product on Sale
```javascript theme={null}
await api.put('/products/123', {
regular_price: '99.99',
sale_price: '79.99'
});
```
### Add Product to Category
```javascript theme={null}
await api.put('/products/123', {
categories: [
{ id: 15 },
{ id: 23 }
]
});
```
### Search Products by SKU
```bash theme={null}
curl "https://example.com/wp-json/wc/v3/products?sku=TSHIRT-001" \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
### Get Featured Products
```bash theme={null}
curl "https://example.com/wp-json/wc/v3/products?featured=true" \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
### Filter by Price Range
```bash theme={null}
curl "https://example.com/wp-json/wc/v3/products?min_price=10&max_price=50" \
-u ck_1234567890abcdef:cs_1234567890abcdef
```
## Error Handling
### Invalid Product ID
```json theme={null}
{
"code": "woocommerce_rest_product_invalid_id",
"message": "Invalid product ID.",
"data": {
"status": 404
}
}
```
### Missing Required Field
```json theme={null}
{
"code": "woocommerce_rest_product_name_required",
"message": "The product name is required.",
"data": {
"status": 400
}
}
```
### Duplicate SKU
```json theme={null}
{
"code": "woocommerce_rest_product_sku_already_exists",
"message": "The SKU already exists on another product.",
"data": {
"status": 400,
"resource_id": 456
}
}
```
## Next Steps
Manage customer orders
Work with customer data
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.