WooCommerce API Customers

The WooCommerce Customers API allows you to manage customer data within your WooCommerce store. This guide covers how to create, update, retrieve, and delete customer records, as well as how to search and filter customers based on various criteria.

What can you do with Customers in the WooCommerce API?

The most common operations people perform on customers using the WooCommerce API.

Action	HTTP Method	Endpoint
Create a Customer	`POST`	`/customers`
List All Customers	`GET`	`/customers`
Retrieve a Customer	`GET`	`/customers/{customerId}`
Update a Customer	`PUT`	`/customers/{customerId}`
Delete a Customer	`DELETE`	`/customers/{customerId}`

Customers in WooCommerce represent individuals or entities who have registered or purchased from your store. Managing customers effectively is crucial for maintaining relationships and driving sales.

Customers are identified by a unique integer ID, which is used to retrieve, update, or delete specific customer records.

To create a customer, you need to provide at least an email address and a password. Additional fields like first name, last name, and username can also be included.

Customers can be searched using various query parameters such as email, role, and search terms. You can also filter by specific IDs or exclude certain IDs from the results.

Properties of a Customer

The properties section lists the key attributes of a customer object in WooCommerce. These properties are essential for managing customer data effectively. Show all properties Only show essential properties

Field Name	Type	Short Description
id	integer	Unique identifier for the resource.
email	string	The email address for the customer. Mandatory.
first_name	string	Customer first name.
last_name	string	Customer last name.
username	string	Customer login name.
date_created	datetime	The date the customer was created, in the site's timezone.
date_modified	datetime	The date the customer was last modified, in the site's timezone.
is_paying_customer	boolean	Is the customer a paying customer?
avatar_url	string	Avatar URL.
date_created_gmt	datetime	The date the customer was created, as GMT.
date_modified_gmt	datetime	The date the customer was last modified, as GMT.
role	string	Customer role.
password	string	Customer password. Write-only.
billing	object	Billing address details.
shipping	object	Shipping address details.
meta_data	array	Meta data associated with the customer.

Show all properties

Filtering and Query Parameters

The WooCommerce Customers API supports a variety of filtering options to help you retrieve specific customer records based on your criteria.

Parameter	Type	Description	Example
`context`	string	Scope under which the request is made; determines fields present in response.	`context=view`
`email`	string	Limit result set to resources with a specific email.	`email=user@example.com`
`exclude`	array	Ensure result set excludes specific IDs.	`exclude=1,2,3`
`include`	array	Limit result set to specific IDs.	`include=4,5,6`
`offset`	integer	Offset the result set by a specific number of items.	`offset=10`
`order`	string	Order sort attribute ascending or descending.	`order=asc`
`orderby`	string	Sort collection by object attribute.	`orderby=name`
`page`	integer	Current page of the collection.	`page=2`
`per_page`	integer	Maximum number of items to be returned in result set.	`per_page=20`
`role`	string	Limit result set to resources with a specific role.	`role=customer`
`search`	string	Limit results to those matching a string.	`search=John`

What to watch out for

When working with the WooCommerce Customers API, there are a few important considerations to keep in mind to avoid common pitfalls.

Email Uniqueness

Each customer must have a unique email address. Attempting to create or update a customer with an existing email will result in an error.

Password Handling

The password field is write-only and cannot be retrieved once set. Ensure you store passwords securely and handle them with care.

Role Management

The role field is read-only and defaults to customer unless specified otherwise during creation. Roles determine the customer's permissions within WooCommerce.

Frequently Asked Questions

Here are some frequently asked questions about the WooCommerce Customers API and how to manage customer data effectively.

How do I find a customer by email in the WooCommerce Customers API?

To find a customer by email, use the GET /customers endpoint with the email query parameter. For example, /customers?email=user@example.com will return the customer with the specified email.

What happens when I update a customer in WooCommerce?

When you update a customer using the PUT /customers/{customerId} endpoint, the customer's details are modified as per the provided data. Ensure that you provide only the fields you wish to update.

Can I delete a customer that has orders in WooCommerce?

Yes, you can delete a customer with orders using the DELETE /customers/{customerId} endpoint. However, you must set the force parameter to true as WooCommerce does not support trashing customers.

How do I handle customer roles in WooCommerce?

Customer roles in WooCommerce determine their permissions and are set during creation. The default role is customer, but you can specify other roles if needed. Note that roles are read-only after creation.

What query parameters are available for searching customers in WooCommerce?

The WooCommerce Customers API supports several query parameters for searching, including email, role, search, include, and exclude. These parameters allow you to filter and refine your search results effectively.