Complete Guide to WooCommerce REST API: Mastering eCommerce Integration

Here’s our complete guide to WooCommerce REST API, covering everything from setup to advanced usage, with examples in PHP, JS, and cURL.

1. Introduction to WooCommerce REST API

The WooCommerce REST API allows developers to interact programmatically with a WooCommerce store. You can manage:

• Orders
• Products
• Customers
• Coupons
• Shipping & Tax
• Reports and analytics

Base URL format:

https://example.com/wp-json/wc/v3/

Core features:

• Full CRUD operations: GET, POST, PUT, DELETE
• Authentication via Consumer Key/Secret or OAuth
• JSON responses
• Supports pagination, filtering, and sorting

2. Setting up WooCommerce REST API

1. Go to WooCommerce → Settings → Advanced → REST API

2. Click Add Key

   • Description: API Key
   • User: Admin or shop manager
   • Permissions: Read, Write, Read/Write
3. Click Generate API Key
4. Copy Consumer Key and Consumer Secret

Keep these keys private; they give full access depending on permission.

3. Authentication Methods

3.1 Basic Authentication (HTTPS required)

• Use Consumer Key as username and Consumer Secret as password
• Works with HTTPS only

cURL example:

curl https://example.com/wp-json/wc/v3/products \
-u consumer_key:consumer_secret

3.2 OAuth 1.0a (HTTP or HTTPS)

• More complex, supports legacy systems
• Not needed if using HTTPS + Basic Auth

4. REST API Endpoints

WooCommerce REST API has standard endpoints, all under /wp-json/wc/v3/:

5. Reading Data (GET Requests)

5.1 Get All Products

GET https://example.com/wp-json/wc/v3/products?per_page=5
-u consumer_key:consumer_secret

JS Example:

fetch('https://example.com/wp-json/wc/v3/products?per_page=5', {
  headers: {
    'Authorization': 'Basic ' + btoa('consumer_key:consumer_secret')
  }
})
.then(res => res.json())
.then(data => console.log(data));

5.2 Filtering & Sorting

• per_page=10 → items per page
• page=2 → pagination
• category=15 → filter by category ID
• orderby=date → sort by date
• order=asc or desc

Example: Get 5 latest products in category 15:

GET /wp-json/wc/v3/products?category=15&per_page=5&orderby=date&order=desc

6. Creating Data (POST Requests)

6.1 Create a Product

POST /wp-json/wc/v3/products
-u consumer_key:consumer_secret
Content-Type: application/json

{
  "name": "API Product",
  "type": "simple",
  "regular_price": "29.99",
  "description": "This product was added via API",
  "categories": [{"id": 15}]
}

PHP Example:

<?php
$data = [
    'name' => 'API Product',
    'type' => 'simple',
    'regular_price' => '29.99',
    'description' => 'Created via REST API',
    'categories' => [['id' => 15]]
];
$ch = curl_init('https://example.com/wp-json/wc/v3/products');
curl_setopt($ch, CURLOPT_USERPWD, 'consumer_key:consumer_secret');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));
?>

7. Updating Data (PUT Requests)

Update a product by ID:

PUT /wp-json/wc/v3/products/123
-u consumer_key:consumer_secret
Content-Type: application/json

{
  "regular_price": "34.99",
  "description": "Updated price via API"
}

• PUT replaces specified fields
• Works for orders, customers, coupons, etc.

8. Deleting Data (DELETE Requests)

DELETE /wp-json/wc/v3/products/123?force=true
-u consumer_key:consumer_secret

• force=true deletes permanently (otherwise goes to trash)

9. Orders

9.1 Get All Orders

GET /wp-json/wc/v3/orders
-u consumer_key:consumer_secret

9.2 Create an Order

POST /wp-json/wc/v3/orders
Content-Type: application/json
-u consumer_key:consumer_secret

{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "1234567890"
  },
  "line_items": [
    {
      "product_id": 123,
      "quantity": 2
    }
  ]
}

9.3 Update an Order

PUT /wp-json/wc/v3/orders/456
{
  "status": "completed"
}

10. Customers

• GET /customers → list all customers
• POST /customers → create new customer
• PUT /customers/{id} → update customer
• DELETE /customers/{id}?force=true → delete customer

Example: Create a customer

POST /wp-json/wc/v3/customers
{
  "email": "newuser@example.com",
  "first_name": "New",
  "last_name": "User",
  "username": "newuser",
  "password": "SecurePass123"
}

11. Webhooks

• Automatically trigger actions in external services
• Example: when a product or order is created
• Endpoint: /webhooks
• Can be created via API or WooCommerce admin panel

12. Pagination & Limits

• per_page → items per page (max 100)
• page → pagination

• Headers provide pagination info:

  • X-WP-Total → total items
  • X-WP-TotalPages → total pages

13. Error Handling

WooCommerce returns standard HTTP status codes:

Example JS error handling:

fetch('/wp-json/wc/v3/products', {
  headers: { 'Authorization': 'Basic ' + btoa('key:secret') }
})
.then(res => {
  if (!res.ok) throw new Error(res.statusText);
  return res.json();
})
.then(data => console.log(data))
.catch(err => console.error('API Error:', err));

14. Tips & Best Practices

• Use HTTPS with Basic Auth
• Always validate input for custom endpoints
• Use caching for high traffic stores
• Limit per_page to avoid large queries
• Use _embed for retrieving related objects efficiently
• Secure keys and restrict permissions per user

15. Official References

• WooCommerce REST API Docs
• Authentication Guide
• PHP API Library

Scale Your WooCommerce Store with NeedleCode

Integrating the WooCommerce REST API can be complex, especially when dealing with high-traffic environments or custom business logic. At NeedleCode, we specialize in building robust, API-driven eCommerce solutions.

How we can help:

• Custom WooCommerce Plugin Development
• Seamless API Integrations & Mobile Apps
• Expert Consultation for Scaling Your Store

Ready to automate your eCommerce? Contact NeedleCode Today

Empowering your digital growth with precision code.