Access your WooCommerce.com order history and invoices programmatically via the REST API.
Overview
↑ Back to topThe Customer Orders API gives you read-only access to your own orders on WooCommerce.com. Use it to automate accounting, sync order data with your systems, or download invoices programmatically.
Prerequisites
↑ Back to top- API access must be enabled on your WooCommerce.com account. Contact your account manager or support to have this turned on.
- You need an application password (a special API token) — see Quick Start below.
Quick Start
↑ Back to topStep 1: Create an Application Password
↑ Back to top- Log in to WooCommerce.com
- Go to My Account and navigate to Application Passwords
- Enter a name for your password (e.g., “Accounting Integration”) and click Create
- Copy the token immediately — it is only displayed once and cannot be retrieved later
Step 2: Make Your First API Call
↑ Back to topReplace you@example.com with your WooCommerce.com login email and YOUR_TOKEN with the application password you just created:
curl -u "you@example.com:YOUR_TOKEN" \\
<https://woocommerce.com/wp-json/wc/v3/orders>
This returns a JSON array of your orders.
Authentication
↑ Back to topTwo authentication methods are supported. Use whichever fits your tooling.
Option A: HTTP Basic Auth
↑ Back to topPass your WooCommerce.com login email as the username and your application password as the password:
curl -u "you@example.com:YOUR_TOKEN" \\
<https://woocommerce.com/wp-json/wc/v3/orders>
Option B: X-API-KEY Header
↑ Back to topPass your application password in the X-API-KEY header (no username needed):
curl -H "X-API-KEY: YOUR_TOKEN" \\
<https://woocommerce.com/wp-json/wc/v3/orders>
Tip: If you use HTTP Basic Auth, the username must match your WooCommerce.com login email or username. Using the wrong username will result in a 401 error.
API Reference
↑ Back to topList Your Orders
↑ Back to topGET /wp-json/wc/v3/orders
Returns a paginated list of your orders. The API automatically scopes results to your account — you will only ever see your own orders.
Common query parameters:
| Parameter | Type | Description |
|---|---|---|
per_page | integer | Number of orders per page (default: 10, max: 100) |
page | integer | Page number |
status | string | Filter by order status (e.g., completed, processing, refunded) |
after | string | Limit to orders created after this ISO 8601 date |
before | string | Limit to orders created before this ISO 8601 date |
Example — get your 5 most recent completed orders:
curl -u "you@example.com:YOUR_TOKEN" \\
"<https://woocommerce.com/wp-json/wc/v3/orders?status=completed&per_page=5>"
Get a Single Order
↑ Back to topGET /wp-json/wc/v3/orders/{id}
Returns full details for a specific order. You can only retrieve orders that belong to your account — requesting someone else’s order returns a 403 Forbidden error.
Example:
curl -u "you@example.com:YOUR_TOKEN" \\
<https://woocommerce.com/wp-json/wc/v3/orders/12345>
Get an Invoice
↑ Back to topGET /wp-json/wc/v3/orders/{id}/invoice
Returns a URL to download the invoice PDF for a specific order.
Requirements:
- The order must have a status of completed or refunded
- Orders with other statuses return a
404 Not Found
Example:
curl -u "you@example.com:YOUR_TOKEN" \\
<https://woocommerce.com/wp-json/wc/v3/orders/12345/invoice>
Response:
{
"order_id": 12345,
"invoice_url": "https://...",
"type": "redirect"
}
Open the invoice_url in a browser or follow the redirect to download the PDF.
The type field indicates how to access the invoice:
redirect— follow the URL to a hosted PDFdownload_url— direct download link for the PDF
Response Format
↑ Back to topOrder responses follow the standard WooCommerce REST API format. Key fields include:
| Field | Description |
|---|---|
id | Order ID |
status | Order status (e.g., completed, processing) |
total | Order total |
currency | Currency code (e.g., USD) |
date_created | When the order was placed |
billing | Billing address and contact details |
shipping | Shipping address |
line_items | Array of purchased products with names, quantities, and prices |
payment_method_title | Payment method used (e.g., “Credit Card”) |
date_paid | When payment was received |
Fields not included in customer responses: internal metadata, customer IP address, customer user agent, and cost-of-goods data. These are omitted for privacy and security.
Important Notes
↑ Back to top- API versions — both
/wc/v2/and/wc/v3/are supported. We recommend usingv3. - Revoking access — you can revoke an application password at any time from My Account > Application Passwords. This immediately disables that token.
- Lost token — if you lose your application password, create a new one. Old tokens cannot be retrieved.
Troubleshooting
↑ Back to top| Issue | Solution |
|---|---|
| 401 Unauthorized | Check that your application password is correct and your username matches your WooCommerce.com login email |
| 403 Forbidden | Your account may not have API access enabled, or you’re trying to access an order that doesn’t belong to you |
| 404 Not Found on invoice | Invoices are only available for completed or refunded orders |
| Token stopped working | Your application password may have been revoked. Create a new one from My Account. |