openapi: 3.1.0
info:
title: WooCommerce REST API
description: >-
The WooCommerce REST API is the primary server-side interface for reading
and writing WooCommerce store data programmatically. It follows REST
conventions, uses JSON for all requests and responses, and is fully
integrated with the WordPress REST API under the /wp-json/wc/v3/ namespace.
The API covers products, product variations, product categories, product
attributes, orders, order notes, order refunds, customers, coupons, tax
rates, shipping zones, payment gateways, settings, webhooks, reports, and
system status. Authentication uses Consumer Key and Consumer Secret pairs
generated in the WooCommerce admin, transmitted over HTTPS via HTTP Basic
Auth or OAuth 1.0a over plain HTTP.
version: 'v3'
contact:
name: WooCommerce Developer Support
url: https://developer.woocommerce.com/docs/apis/rest-api/
termsOfService: https://woocommerce.com/terms-conditions/
externalDocs:
description: WooCommerce REST API Documentation
url: https://woocommerce.github.io/woocommerce-rest-api-docs/
servers:
- url: https://example.com/wp-json/wc/v3
description: Production Server (replace example.com with your store domain)
tags:
- name: Products
description: Create, retrieve, update, and delete store products and their variations
- name: Product Variations
description: Manage variations of variable products including price, stock, and attributes
- name: Product Categories
description: Manage product categories used to organize the store catalog
- name: Product Attributes
description: Manage global product attributes and their terms
- name: Product Tags
description: Manage product tags used to label and filter products
- name: Product Reviews
description: Manage customer reviews on products
- name: Orders
description: Create, retrieve, update, and delete customer orders
- name: Order Notes
description: Manage private and customer-facing notes on orders
- name: Order Refunds
description: Create and retrieve refunds associated with orders
- name: Customers
description: Create, retrieve, update, and delete customer accounts
- name: Coupons
description: Create, retrieve, update, and delete discount coupons
- name: Tax Rates
description: Manage tax rates and tax classes applied at checkout
- name: Shipping Zones
description: Manage shipping zones, their locations, and shipping methods
- name: Payment Gateways
description: Retrieve and configure available payment gateways
- name: Webhooks
description: Create and manage webhooks that deliver event notifications to URLs
- name: Settings
description: Retrieve and update WooCommerce store settings groups and options
- name: Reports
description: Retrieve aggregated sales, product, and customer report data
- name: System Status
description: Retrieve system environment, active plugins, and store configuration status
security:
- basicAuth: []
paths:
/products:
get:
operationId: listProducts
summary: WooCommerce List All Products
description: >-
Returns a paginated list of products in the store. Supports filtering by
status, category, tag, SKU, featured flag, on-sale flag, price range,
stock status, and date ranges. Results are sorted by date by default.
Use the page and per_page parameters to paginate through large catalogs.
tags:
- Products
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- name: status
in: query
description: >-
Filter products by publication status. Options: any, draft, pending,
private, publish.
required: false
schema:
type: string
enum: [any, draft, pending, private, publish]
example: any
- name: category
in: query
description: Filter products by category ID.
required: false
schema:
type: string
example: string-value
- name: tag
in: query
description: Filter products by tag ID.
required: false
schema:
type: string
example: string-value
- name: on_sale
in: query
description: Limit results to products on sale when true.
required: false
schema:
type: boolean
example: true
- name: featured
in: query
description: Limit results to featured products when true.
required: false
schema:
type: boolean
example: true
- name: stock_status
in: query
description: >-
Filter by stock status. Options: instock, outofstock, onbackorder.
required: false
schema:
type: string
enum: [instock, outofstock, onbackorder]
example: instock
responses:
'200':
description: Successful list of products
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Product'
examples:
listProducts200Example:
summary: Default listProducts 200 response
x-microcks-default: true
value:
- id: 1
name: Example Name
slug: string-value
permalink: https://example.com/path
type: simple
status: draft
featured: true
description: A sample description
short_description: A sample description
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
purchasable: true
total_sales: 1
virtual: true
downloadable: true
manage_stock: true
stock_quantity: 1
stock_status: instock
weight: string-value
dimensions: &id001
length: string-value
width: string-value
height: string-value
categories: &id002
- id: 1
name: Example Name
slug: string-value
tags: &id003
- id: 1
name: Example Name
slug: string-value
images: &id004
- string-value
attributes: &id005
- string-value
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
meta_data: &id006
- string-value
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createProduct
summary: WooCommerce Create a Product
description: >-
Creates a new product in the store. Requires at minimum a product name.
Products can be simple, grouped, external/affiliate, or variable type.
Pricing, stock management, shipping, tax settings, categories, tags,
images, and attributes are all configurable at creation time.
tags:
- Products
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductInput'
responses:
'201':
description: Product created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
examples:
createProduct201Example:
summary: Default createProduct 201 response
x-microcks-default: true
value:
id: 1
name: Example Name
slug: string-value
permalink: https://example.com/path
type: simple
status: draft
featured: true
description: A sample description
short_description: A sample description
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
purchasable: true
total_sales: 1
virtual: true
downloadable: true
manage_stock: true
stock_quantity: 1
stock_status: instock
weight: string-value
dimensions: *id001
categories: *id002
tags: *id003
images: *id004
attributes: *id005
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
meta_data: *id006
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/{id}:
get:
operationId: getProduct
summary: WooCommerce Retrieve a Product
description: >-
Returns the details of a single product identified by its numeric ID.
Includes all product properties such as pricing, stock, images,
categories, tags, attributes, and metadata.
tags:
- Products
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Product details
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
examples:
getProduct200Example:
summary: Default getProduct 200 response
x-microcks-default: true
value:
id: 1
name: Example Name
slug: string-value
permalink: https://example.com/path
type: simple
status: draft
featured: true
description: A sample description
short_description: A sample description
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
purchasable: true
total_sales: 1
virtual: true
downloadable: true
manage_stock: true
stock_quantity: 1
stock_status: instock
weight: string-value
dimensions: *id001
categories: *id002
tags: *id003
images: *id004
attributes: *id005
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
meta_data: *id006
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateProduct
summary: WooCommerce Update a Product
description: >-
Updates an existing product identified by its numeric ID. Only the
properties included in the request body are updated; omitted properties
retain their current values.
tags:
- Products
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductInput'
responses:
'200':
description: Product updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
examples:
updateProduct200Example:
summary: Default updateProduct 200 response
x-microcks-default: true
value:
id: 1
name: Example Name
slug: string-value
permalink: https://example.com/path
type: simple
status: draft
featured: true
description: A sample description
short_description: A sample description
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
purchasable: true
total_sales: 1
virtual: true
downloadable: true
manage_stock: true
stock_quantity: 1
stock_status: instock
weight: string-value
dimensions: *id001
categories: *id002
tags: *id003
images: *id004
attributes: *id005
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
meta_data: *id006
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteProduct
summary: WooCommerce Delete a Product
description: >-
Deletes a product by its numeric ID. By default the product is moved to
the trash. Set the force parameter to true to permanently delete the
product and bypass the trash.
tags:
- Products
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/force'
responses:
'200':
description: Product deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
examples:
deleteProduct200Example:
summary: Default deleteProduct 200 response
x-microcks-default: true
value:
id: 1
name: Example Name
slug: string-value
permalink: https://example.com/path
type: simple
status: draft
featured: true
description: A sample description
short_description: A sample description
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
purchasable: true
total_sales: 1
virtual: true
downloadable: true
manage_stock: true
stock_quantity: 1
stock_status: instock
weight: string-value
dimensions: *id001
categories: *id002
tags: *id003
images: *id004
attributes: *id005
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
meta_data: *id006
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/batch:
post:
operationId: batchUpdateProducts
summary: WooCommerce Batch Create, Update, and Delete Products
description: >-
Performs batch create, update, and delete operations on products in a
single request. Pass arrays of product objects under the create, update,
and delete keys respectively. Delete accepts an array of product IDs.
tags:
- Products
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchProductRequest'
responses:
'200':
description: Batch operation completed
content:
application/json:
schema:
$ref: '#/components/schemas/BatchProductResponse'
examples:
batchUpdateProducts200Example:
summary: Default batchUpdateProducts 200 response
x-microcks-default: true
value:
create: &id019
- string-value
update: &id020
- string-value
delete: &id021
- string-value
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/{product_id}/variations:
get:
operationId: listProductVariations
summary: WooCommerce List All Product Variations
description: >-
Returns all variations for a variable product identified by product_id.
Each variation has its own pricing, SKU, stock, image, and attribute
combination.
tags:
- Product Variations
parameters:
- $ref: '#/components/parameters/product_id'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
responses:
'200':
description: List of product variations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProductVariation'
examples:
listProductVariations200Example:
summary: Default listProductVariations 200 response
x-microcks-default: true
value:
- id: 1
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
status: draft
manage_stock: true
stock_quantity: 1
stock_status: instock
image:
id: {}
src: {}
name: {}
alt: {}
attributes: &id007
- id: 1
name: Example Name
option: string-value
meta_data: &id008
- string-value
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createProductVariation
summary: WooCommerce Create a Product Variation
description: >-
Creates a new variation for a variable product. The variation inherits
the parent product's attributes and can override price, SKU, stock,
weight, dimensions, and image independently.
tags:
- Product Variations
parameters:
- $ref: '#/components/parameters/product_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductVariationInput'
responses:
'201':
description: Variation created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductVariation'
examples:
createProductVariation201Example:
summary: Default createProductVariation 201 response
x-microcks-default: true
value:
id: 1
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
status: draft
manage_stock: true
stock_quantity: 1
stock_status: instock
image:
id: 1
src: https://example.com/path
name: Example Name
alt: string-value
attributes: *id007
meta_data: *id008
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/{product_id}/variations/{id}:
get:
operationId: getProductVariation
summary: WooCommerce Retrieve a Product Variation
description: >-
Returns the details of a single product variation identified by the
parent product ID and the variation ID.
tags:
- Product Variations
parameters:
- $ref: '#/components/parameters/product_id'
- $ref: '#/components/parameters/id'
responses:
'200':
description: Product variation details
content:
application/json:
schema:
$ref: '#/components/schemas/ProductVariation'
examples:
getProductVariation200Example:
summary: Default getProductVariation 200 response
x-microcks-default: true
value:
id: 1
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
status: draft
manage_stock: true
stock_quantity: 1
stock_status: instock
image:
id: 1
src: https://example.com/path
name: Example Name
alt: string-value
attributes: *id007
meta_data: *id008
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateProductVariation
summary: WooCommerce Update a Product Variation
description: >-
Updates an existing variation for a variable product. Only the fields
provided in the request body are changed.
tags:
- Product Variations
parameters:
- $ref: '#/components/parameters/product_id'
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductVariationInput'
responses:
'200':
description: Variation updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductVariation'
examples:
updateProductVariation200Example:
summary: Default updateProductVariation 200 response
x-microcks-default: true
value:
id: 1
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
status: draft
manage_stock: true
stock_quantity: 1
stock_status: instock
image:
id: 1
src: https://example.com/path
name: Example Name
alt: string-value
attributes: *id007
meta_data: *id008
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteProductVariation
summary: WooCommerce Delete a Product Variation
description: >-
Deletes a specific variation from a variable product. Set force to true
to permanently delete rather than trash.
tags:
- Product Variations
parameters:
- $ref: '#/components/parameters/product_id'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/force'
responses:
'200':
description: Variation deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductVariation'
examples:
deleteProductVariation200Example:
summary: Default deleteProductVariation 200 response
x-microcks-default: true
value:
id: 1
sku: string-value
price: string-value
regular_price: string-value
sale_price: string-value
on_sale: true
status: draft
manage_stock: true
stock_quantity: 1
stock_status: instock
image:
id: 1
src: https://example.com/path
name: Example Name
alt: string-value
attributes: *id007
meta_data: *id008
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/categories:
get:
operationId: listProductCategories
summary: WooCommerce List All Product Categories
description: >-
Returns all product categories. Supports filtering by parent category,
hiding empty categories, and ordering by various fields. Categories are
hierarchical and can be nested.
tags:
- Product Categories
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
- $ref: '#/components/parameters/search'
- name: hide_empty
in: query
description: Whether to hide resources not assigned to any products.
required: false
schema:
type: boolean
example: true
- name: parent
in: query
description: Filter categories by parent category ID.
required: false
schema:
type: integer
example: 1
responses:
'200':
description: List of product categories
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProductCategory'
examples:
listProductCategories200Example:
summary: Default listProductCategories 200 response
x-microcks-default: true
value:
- id: 1
name: Example Name
slug: string-value
parent: 1
description: A sample description
display: string-value
image:
id: {}
src: {}
name: {}
alt: {}
menu_order: 1
count: 1
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createProductCategory
summary: WooCommerce Create a Product Category
description: >-
Creates a new product category. Categories can be nested by supplying a
parent ID. A slug is generated automatically from the name if not
provided.
tags:
- Product Categories
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCategoryInput'
responses:
'201':
description: Category created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCategory'
examples:
createProductCategory201Example:
summary: Default createProductCategory 201 response
x-microcks-default: true
value:
id: 1
name: Example Name
slug: string-value
parent: 1
description: A sample description
display: string-value
image:
id: 1
src: https://example.com/path
name: Example Name
alt: string-value
menu_order: 1
count: 1
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/products/categories/{id}:
get:
operationId: getProductCategory
summary: WooCommerce Retrieve a Product Category
description: Returns a single product category by its numeric ID.
tags:
- Product Categories
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Product category details
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCategory'
examples:
getProductCategory200Example:
summary: Default getProductCategory 200 response
x-microcks-default: true
value:
id: 1
name: Example Name
slug: string-value
parent: 1
description: A sample description
display: string-value
image:
id: 1
src: https://example.com/path
name: Example Name
alt: string-value
menu_order: 1
count: 1
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateProductCategory
summary: WooCommerce Update a Product Category
description: Updates a product category by its numeric ID.
tags:
- Product Categories
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
ap
# --- truncated at 32 KB (157 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/woocommerce/refs/heads/main/openapi/woocommerce-rest-api-openapi.yml