openapi: 3.1.0
info:
title: WooCommerce REST Cart Orders 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/
servers:
- url: https://example.com/wp-json/wc/v3
description: Production Server (replace example.com with your store domain)
security:
- basicAuth: []
tags:
- name: Orders
description: Create, retrieve, update, and delete customer orders
paths:
/orders:
get:
operationId: listOrders
summary: WooCommerce List All Orders
description: Returns a paginated list of orders. Supports filtering by status, customer ID, product ID, date ranges, and more. Orders are sorted by date_created descending by default.
tags:
- Orders
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 orders by status. Options: any, pending, processing, on-hold, completed, cancelled, refunded, failed, trash.'
required: false
schema:
type: string
enum:
- any
- pending
- processing
- on-hold
- completed
- cancelled
- refunded
- failed
- trash
example: any
- name: customer
in: query
description: Filter orders by customer ID.
required: false
schema:
type: integer
example: 1
- name: product
in: query
description: Filter orders that contain a specific product ID.
required: false
schema:
type: integer
example: 1
responses:
'200':
description: List of orders
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Order'
examples:
listOrders200Example:
summary: Default listOrders 200 response
x-microcks-default: true
value:
- id: 1
parent_id: 1
number: string-value
order_key: string-value
status: pending
currency: string-value
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
date_completed: '2026-05-03T14:30:00Z'
discount_total: string-value
discount_tax: string-value
shipping_total: string-value
shipping_tax: string-value
cart_tax: string-value
total: string-value
total_tax: string-value
customer_id: 1
customer_note: string-value
billing:
first_name: {}
last_name: {}
company: {}
address_1: {}
address_2: {}
city: {}
state: {}
postcode: {}
country: {}
email: {}
phone: {}
shipping:
first_name: {}
last_name: {}
company: {}
address_1: {}
address_2: {}
city: {}
state: {}
postcode: {}
country: {}
email: {}
phone: {}
payment_method: string-value
payment_method_title: Example Name
transaction_id: '500123'
line_items:
- string-value
meta_data:
- string-value
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createOrder
summary: WooCommerce Create an Order
description: Creates a new order. All order fields including billing, shipping, line items, coupons, shipping lines, and fee lines can be set at creation time. Customer ID is optional; guest checkout is supported.
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderInput'
responses:
'201':
description: Order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
createOrder201Example:
summary: Default createOrder 201 response
x-microcks-default: true
value:
id: 1
parent_id: 1
number: string-value
order_key: string-value
status: pending
currency: string-value
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
date_completed: '2026-05-03T14:30:00Z'
discount_total: string-value
discount_tax: string-value
shipping_total: string-value
shipping_tax: string-value
cart_tax: string-value
total: string-value
total_tax: string-value
customer_id: 1
customer_note: string-value
billing:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
shipping:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
payment_method: string-value
payment_method_title: Example Name
transaction_id: '500123'
line_items:
- string-value
meta_data:
- string-value
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orders/{id}:
get:
operationId: getOrder
summary: WooCommerce Retrieve an Order
description: Returns a single order by its numeric ID including all line items, totals, billing, and shipping details.
tags:
- Orders
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Order details
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
getOrder200Example:
summary: Default getOrder 200 response
x-microcks-default: true
value:
id: 1
parent_id: 1
number: string-value
order_key: string-value
status: pending
currency: string-value
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
date_completed: '2026-05-03T14:30:00Z'
discount_total: string-value
discount_tax: string-value
shipping_total: string-value
shipping_tax: string-value
cart_tax: string-value
total: string-value
total_tax: string-value
customer_id: 1
customer_note: string-value
billing:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
shipping:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
payment_method: string-value
payment_method_title: Example Name
transaction_id: '500123'
line_items:
- string-value
meta_data:
- string-value
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateOrder
summary: WooCommerce Update an Order
description: Updates an existing order. Common use cases include changing order status, updating billing or shipping addresses, and modifying line item quantities. Only fields included in the request are changed.
tags:
- Orders
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderInput'
responses:
'200':
description: Order updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
updateOrder200Example:
summary: Default updateOrder 200 response
x-microcks-default: true
value:
id: 1
parent_id: 1
number: string-value
order_key: string-value
status: pending
currency: string-value
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
date_completed: '2026-05-03T14:30:00Z'
discount_total: string-value
discount_tax: string-value
shipping_total: string-value
shipping_tax: string-value
cart_tax: string-value
total: string-value
total_tax: string-value
customer_id: 1
customer_note: string-value
billing:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
shipping:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
payment_method: string-value
payment_method_title: Example Name
transaction_id: '500123'
line_items:
- string-value
meta_data:
- string-value
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteOrder
summary: WooCommerce Delete an Order
description: Deletes an order by its numeric ID. Set force to true to permanently delete rather than moving the order to the trash.
tags:
- Orders
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/force'
responses:
'200':
description: Order deleted
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
deleteOrder200Example:
summary: Default deleteOrder 200 response
x-microcks-default: true
value:
id: 1
parent_id: 1
number: string-value
order_key: string-value
status: pending
currency: string-value
date_created: '2026-05-03T14:30:00Z'
date_modified: '2026-05-03T14:30:00Z'
date_completed: '2026-05-03T14:30:00Z'
discount_total: string-value
discount_tax: string-value
shipping_total: string-value
shipping_tax: string-value
cart_tax: string-value
total: string-value
total_tax: string-value
customer_id: 1
customer_note: string-value
billing:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
shipping:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
payment_method: string-value
payment_method_title: Example Name
transaction_id: '500123'
line_items:
- string-value
meta_data:
- string-value
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/order/{id}:
get:
operationId: getStoreOrder
summary: WooCommerce Retrieve a Customer Order
description: Returns a single order by ID. Only returns orders belonging to the currently authenticated customer. Used for order confirmation and account order history pages.
tags:
- Orders
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Customer order details
content:
application/json:
schema:
$ref: '#/components/schemas/StoreOrder'
examples:
getStoreOrder200Example:
summary: Default getStoreOrder 200 response
x-microcks-default: true
value:
id: 1
number: string-value
status: active
date_created: '2026-05-03T14:30:00Z'
total: string-value
billing:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
shipping:
first_name: Example Name
last_name: Example Name
company: string-value
address_1: string-value
address_2: string-value
city: string-value
state: string-value
postcode: string-value
country: string-value
email: user@example.com
phone: string-value
items:
- id: 1
name: Example Name
quantity: 1
total: string-value
'401':
$ref: '#/components/responses/Unauthorized_2'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
Error_2:
type: object
description: Error response returned when a request fails.
properties:
code:
type: string
description: Machine-readable error code.
example: string-value
message:
type: string
description: Human-readable error message.
example: string-value
data:
type: object
description: Additional context including HTTP status.
properties:
status:
type: integer
description: HTTP status code.
example:
status: 1
StoreAddress:
type: object
description: A customer billing or shipping address in the Store API context.
properties:
first_name:
type: string
description: First name.
example: Example Name
last_name:
type: string
description: Last name.
example: Example Name
company:
type: string
description: Company name.
example: string-value
address_1:
type: string
description: Address line 1.
example: string-value
address_2:
type: string
description: Address line 2.
example: string-value
city:
type: string
description: City.
example: string-value
state:
type: string
description: State or province code.
example: string-value
postcode:
type: string
description: Postal code.
example: string-value
country:
type: string
description: ISO 3166-1 alpha-2 country code.
example: string-value
email:
type: string
format: email
description: Email address (billing only).
example: user@example.com
phone:
type: string
description: Phone number.
example: string-value
MetaData:
type: object
description: Custom metadata key-value entry.
properties:
id:
type: integer
description: Metadata unique identifier.
example: 1
key:
type: string
description: Metadata key.
example: string-value
value:
type: string
description: Metadata value.
example: string-value
LineItem:
type: object
description: A product line item within an order.
properties:
id:
type: integer
description: Line item unique identifier.
example: 1
name:
type: string
description: Product name at time of purchase.
example: Example Name
product_id:
type: integer
description: Product ID.
example: 1
variation_id:
type: integer
description: Variation ID (0 if not a variation).
example: 1
quantity:
type: integer
description: Quantity ordered.
example: 1
tax_class:
type: string
description: Tax class used for this line item.
example: string-value
subtotal:
type: string
description: Line subtotal (before discounts) as a decimal string.
example: string-value
subtotal_tax:
type: string
description: Line subtotal tax as a decimal string.
example: string-value
total:
type: string
description: Line total (after discounts) as a decimal string.
example: string-value
total_tax:
type: string
description: Line total tax as a decimal string.
example: string-value
sku:
type: string
description: Product SKU.
example: string-value
price:
type: number
description: Product price at time of purchase.
example: 10.5
meta_data:
type: array
description: Metadata for the line item (e.g. variation attributes).
items:
$ref: '#/components/schemas/MetaData'
example:
- string-value
StoreOrder:
type: object
description: A customer order retrieved via the Store API.
properties:
id:
type: integer
description: Order unique identifier.
example: 1
number:
type: string
description: Human-readable order number.
example: string-value
status:
type: string
description: Order status.
example: active
date_created:
type: string
format: date-time
description: Date the order was created.
example: '2026-05-03T14:30:00Z'
total:
type: string
description: Order grand total.
example: string-value
billing:
$ref: '#/components/schemas/StoreAddress'
shipping:
$ref: '#/components/schemas/StoreAddress'
items:
type: array
description: Items in the order.
items:
type: object
properties:
id:
type: integer
description: Line item ID.
name:
type: string
description: Product name.
quantity:
type: integer
description: Quantity ordered.
total:
type: string
description: Line item total.
example:
- id: 1
name: Example Name
quantity: 1
total: string-value
Address:
type: object
description: Billing or shipping address associated with a customer or order.
properties:
first_name:
type: string
description: First name.
example: Example Name
last_name:
type: string
description: Last name.
example: Example Name
company:
type: string
description: Company name.
example: string-value
address_1:
type: string
description: Address line 1.
example: string-value
address_2:
type: string
description: Address line 2.
example: string-value
city:
type: string
description: City name.
example: string-value
state:
type: string
description: ISO code or name of the state, province, or district.
example: string-value
postcode:
type: string
description: Postal code.
example: string-value
country:
type: string
description: ISO 3166-1 alpha-2 country code.
example: string-value
email:
type: string
format: email
description: Email address (billing only).
example: user@example.com
phone:
type: string
description: Phone number (billing only).
example: string-value
Order:
type: object
description: A WooCommerce customer order.
properties:
id:
type: integer
description: Order unique identifier.
example: 1
parent_id:
type: integer
description: Parent order ID (for order refunds and child orders).
example: 1
number:
type: string
description: Order number displayed to customers.
example: string-value
order_key:
type: string
description: Order key used to verify order ownership.
example: string-value
status:
type: string
description: 'Order status. Options: pending, processing, on-hold, completed, cancelled, refunded, failed, trash.'
enum:
- pending
- processing
- on-hold
- completed
- cancelled
- refunded
- failed
- trash
example: pending
currency:
type: string
description: ISO 4217 currency code used for the order.
example: string-value
date_created:
type: string
format: date-time
description: Date the order was created.
example: '2026-05-03T14:30:00Z'
date_modified:
type: string
format: date-time
description: Date the order was last modified.
example: '2026-05-03T14:30:00Z'
date_completed:
type: string
format: date-time
description: Date the order was marked as completed.
nullable: true
example: '2026-05-03T14:30:00Z'
discount_total:
type: string
description: Total discount applied to the order as a decimal string.
example: string-value
discount_tax:
type: string
description: Total discount tax as a decimal string.
example: string-value
shipping_total:
type: string
description: Total shipping cost as a decimal string.
example: string-value
shipping_tax:
type: string
description: Total shipping tax as a decimal string.
example: string-value
cart_tax:
type: string
description: Total cart item taxes as a decimal string.
example: string-value
total:
type: string
description: Grand total as a decimal string.
example: string-value
total_tax:
type: string
description: Total tax as a decimal string.
example: string-value
customer_id:
type: integer
description: Customer ID (0 for guest orders).
example: 1
customer_note:
type: string
description: Note left by the customer at checkout.
example: string-value
billing:
$ref: '#/components/schemas/Address'
shipping:
$ref: '#/components/schemas/Address'
payment_method:
type: string
description: Payment method ID (e.g. stripe, paypal).
example: string-value
payment_method_title:
type: string
description: Human-readable payment method name.
example: Example Name
transaction_id:
type: string
description: Payment gateway transaction ID.
example: '500123'
line_items:
type: array
description: Line items in the order.
items:
$ref: '#/components/schemas/LineItem'
example:
- string-value
meta_data:
type: array
description: Custom metadata attached to the order.
items:
$ref: '#/components/schemas/MetaData'
example:
- string-value
OrderInput:
type: object
description: Input for creating or updating an order.
properties:
status:
type: string
description: Order status.
enum:
- pending
- processing
- on-hold
- completed
- cancelled
- refunded
- failed
example: pending
customer_id:
type: integer
description: Customer ID (0 for guest).
example: 1
customer_note:
type: string
description: Note from customer.
example: string-value
billing:
$ref: '#/components/schemas/Address'
shipping:
$ref: '#/components/schemas/Address'
payment_method:
type: string
description: Payment method ID.
example: string-value
payment_method_title:
type: string
description: Payment method display name.
example: Example Name
line_items:
type: array
description: Line items to include in the order.
items:
$ref: '#/components/schemas/LineItem'
example:
- string-value
meta_data:
type: array
description: Custom metadata.
items:
$ref: '#/components/schemas/MetaData'
example:
- string-value
Error:
type: object
properties:
code:
type: string
description: Machine-readable error code.
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/woocommerce/refs/heads/main/openapi/woocommerce-orders-api-openapi.yml