Customers API

The Customers endpoint allows you to create, read, update, and delete customers in your WooCommerce store.

The Customer Object

Customer Properties

integer

required

Unique identifier for the customer. Read-only.

string

The date the customer was created, in ISO8601 format. Read-only.

string

The date the customer was last modified, in ISO8601 format. Read-only.

string

required

The email address for the customer.

string

Customer first name.

string

Customer last name.

string

Customer role. Read-only.

string

Customer login name. Cannot be changed after creation.

string

Customer password. Write-only (never returned in responses).

object

Billing address.

{
  "first_name": "John",
  "last_name": "Doe",
  "company": "Acme Inc",
  "address_1": "123 Main St",
  "address_2": "Apt 4",
  "city": "New York",
  "state": "NY",
  "postcode": "10001",
  "country": "US",
  "email": "john@example.com",
  "phone": "555-1234"
}

object

Shipping address.

{
  "first_name": "John",
  "last_name": "Doe",
  "company": "Acme Inc",
  "address_1": "123 Main St",
  "address_2": "Apt 4",
  "city": "New York",
  "state": "NY",
  "postcode": "10001",
  "country": "US"
}

boolean

Whether the customer has made a purchase. Read-only.

string

Avatar URL. Read-only.

List All Customers

Retrieve a list of all customers in your store.

curl https://example.com/wp-json/wc/v3/customers \
  -u ck_1234567890abcdef:cs_1234567890abcdef

const response = await api.get('/customers');
console.log(response.data);

response = requests.get(
    'https://example.com/wp-json/wc/v3/customers',
    auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
customers = response.json()

$customers = $woocommerce->get('customers');

Query Parameters

integer

default:"1"

Current page of the collection.

integer

default:"10"

Maximum number of items to return (max 100).

string

Limit results to those matching a string (searches username, email, first name, last name).

string

Limit result set to customers with a specific email.

string

default:"all"

Limit result set to customers with specific role. Options: all, administrator, editor, author, contributor, subscriber, customer, shop_manager

string

default:"name"

Sort customers by attribute. Options: id, include, name, registered_date

string

default:"asc"

Order sort direction. Options: asc, desc

Example Response

[
  {
    "id": 789,
    "date_created": "2024-01-10T12:00:00",
    "date_created_gmt": "2024-01-10T17:00:00",
    "date_modified": "2024-02-15T09:30:00",
    "date_modified_gmt": "2024-02-15T14:30:00",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "customer",
    "username": "johndoe",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Inc",
      "address_1": "123 Main Street",
      "address_2": "Suite 100",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 123-4567"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Inc",
      "address_1": "123 Main Street",
      "address_2": "Suite 100",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US"
    },
    "is_paying_customer": true,
    "avatar_url": "https://secure.gravatar.com/avatar/...",
    "meta_data": []
  }
]

Retrieve a Customer

Get details of a single customer by ID.

curl https://example.com/wp-json/wc/v3/customers/789 \
  -u ck_1234567890abcdef:cs_1234567890abcdef

const response = await api.get('/customers/789');
console.log(response.data);

response = requests.get(
    'https://example.com/wp-json/wc/v3/customers/789',
    auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
customer = response.json()

$customer = $woocommerce->get('customers/789');

Create a Customer

Create a new customer in your store.

curl -X POST https://example.com/wp-json/wc/v3/customers \
  -u ck_1234567890abcdef:cs_1234567890abcdef \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "username": "janesmith",
    "password": "SecurePassword123!",
    "billing": {
      "first_name": "Jane",
      "last_name": "Smith",
      "company": "",
      "address_1": "456 Oak Avenue",
      "address_2": "",
      "city": "Los Angeles",
      "state": "CA",
      "postcode": "90001",
      "country": "US",
      "email": "jane.smith@example.com",
      "phone": "(555) 987-6543"
    },
    "shipping": {
      "first_name": "Jane",
      "last_name": "Smith",
      "company": "",
      "address_1": "456 Oak Avenue",
      "address_2": "",
      "city": "Los Angeles",
      "state": "CA",
      "postcode": "90001",
      "country": "US"
    }
  }'

const newCustomer = {
  email: 'jane.smith@example.com',
  first_name: 'Jane',
  last_name: 'Smith',
  username: 'janesmith',
  password: 'SecurePassword123!',
  billing: {
    first_name: 'Jane',
    last_name: 'Smith',
    address_1: '456 Oak Avenue',
    city: 'Los Angeles',
    state: 'CA',
    postcode: '90001',
    country: 'US',
    email: 'jane.smith@example.com',
    phone: '(555) 987-6543'
  },
  shipping: {
    first_name: 'Jane',
    last_name: 'Smith',
    address_1: '456 Oak Avenue',
    city: 'Los Angeles',
    state: 'CA',
    postcode: '90001',
    country: 'US'
  }
};

const response = await api.post('/customers', newCustomer);
console.log(response.data);

data = {
    'email': 'jane.smith@example.com',
    'first_name': 'Jane',
    'last_name': 'Smith',
    'username': 'janesmith',
    'password': 'SecurePassword123!',
    'billing': {
        'first_name': 'Jane',
        'last_name': 'Smith',
        'address_1': '456 Oak Avenue',
        'city': 'Los Angeles',
        'state': 'CA',
        'postcode': '90001',
        'country': 'US',
        'email': 'jane.smith@example.com',
        'phone': '(555) 987-6543'
    },
    'shipping': {
        'first_name': 'Jane',
        'last_name': 'Smith',
        'address_1': '456 Oak Avenue',
        'city': 'Los Angeles',
        'state': 'CA',
        'postcode': '90001',
        'country': 'US'
    }
}

response = requests.post(
    'https://example.com/wp-json/wc/v3/customers',
    json=data,
    auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
customer = response.json()

$data = [
    'email' => 'jane.smith@example.com',
    'first_name' => 'Jane',
    'last_name' => 'Smith',
    'username' => 'janesmith',
    'password' => 'SecurePassword123!',
    'billing' => [
        'first_name' => 'Jane',
        'last_name' => 'Smith',
        'address_1' => '456 Oak Avenue',
        'city' => 'Los Angeles',
        'state' => 'CA',
        'postcode' => '90001',
        'country' => 'US',
        'email' => 'jane.smith@example.com',
        'phone' => '(555) 987-6543'
    ],
    'shipping' => [
        'first_name' => 'Jane',
        'last_name' => 'Smith',
        'address_1' => '456 Oak Avenue',
        'city' => 'Los Angeles',
        'state' => 'CA',
        'postcode' => '90001',
        'country' => 'US'
    ]
];

$customer = $woocommerce->post('customers', $data);

Required Fields

string

required

Customer email address (must be unique)

Important Fields

string

Customer login name. Auto-generated from email if not provided. Cannot be changed after creation.

string

Customer password. Auto-generated if not provided.

string

Customer first name

string

Customer last name

object

Billing address object (see Customer Object above)

object

Shipping address object (see Customer Object above)

Update a Customer

Update an existing customer.

curl -X PUT https://example.com/wp-json/wc/v3/customers/789 \
  -u ck_1234567890abcdef:cs_1234567890abcdef \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "billing": {
      "phone": "(555) 111-2222"
    }
  }'

const updates = {
  first_name: 'Jane',
  last_name: 'Doe',
  billing: {
    phone: '(555) 111-2222'
  }
};

const response = await api.put('/customers/789', updates);
console.log(response.data);

data = {
    'first_name': 'Jane',
    'last_name': 'Doe',
    'billing': {
        'phone': '(555) 111-2222'
    }
}

response = requests.put(
    'https://example.com/wp-json/wc/v3/customers/789',
    json=data,
    auth=HTTPBasicAuth(consumer_key, consumer_secret)
)
customer = response.json()

$data = [
    'first_name' => 'Jane',
    'last_name' => 'Doe',
    'billing' => [
        'phone' => '(555) 111-2222'
    ]
];

$customer = $woocommerce->put('customers/789', $data);

The username field cannot be updated after a customer is created.

Delete a Customer

Delete a customer permanently.

curl -X DELETE https://example.com/wp-json/wc/v3/customers/789?force=true \
  -u ck_1234567890abcdef:cs_1234567890abcdef

await api.delete('/customers/789', { params: { force: true } });

requests.delete(
    'https://example.com/wp-json/wc/v3/customers/789',
    params={'force': True},
    auth=HTTPBasicAuth(consumer_key, consumer_secret)
)

$woocommerce->delete('customers/789', ['force' => true]);

Parameters

boolean

default:"false"

Required to be true as customers do not support trashing.

integer

User ID to reassign posts to. Required when deleting a customer with posts.

Deleting a customer is permanent and cannot be undone. Consider deactivating the user account instead if you need to preserve data.

Batch Update Customers

Create, update, and delete multiple customers in a single request.

curl -X POST https://example.com/wp-json/wc/v3/customers/batch \
  -u ck_1234567890abcdef:cs_1234567890abcdef \
  -H "Content-Type: application/json" \
  -d '{
    "create": [
      {
        "email": "customer1@example.com",
        "first_name": "Customer",
        "last_name": "One",
        "username": "customer1",
        "password": "Password123!"
      }
    ],
    "update": [
      {
        "id": 789,
        "billing": {
          "phone": "(555) 999-8888"
        }
      }
    ],
    "delete": [
      456
    ]
  }'

Common Use Cases

Find Customer by Email

curl "https://example.com/wp-json/wc/v3/customers?email=john.doe@example.com" \
  -u ck_1234567890abcdef:cs_1234567890abcdef

Search Customers

curl "https://example.com/wp-json/wc/v3/customers?search=john" \
  -u ck_1234567890abcdef:cs_1234567890abcdef

Update Customer Address

await api.put('/customers/789', {
  shipping: {
    first_name: 'John',
    last_name: 'Doe',
    address_1: '789 New Street',
    city: 'Boston',
    state: 'MA',
    postcode: '02101',
    country: 'US'
  }
});

Get Customer Orders

To retrieve a customer’s orders, use the Orders endpoint with the customer parameter:

curl "https://example.com/wp-json/wc/v3/orders?customer=789" \
  -u ck_1234567890abcdef:cs_1234567890abcdef

Reset Customer Password

await api.put('/customers/789', {
  password: 'NewSecurePassword123!'
});

Customer Downloads

Manage downloadable product permissions for customers.

List Customer Downloads

curl https://example.com/wp-json/wc/v3/customers/789/downloads \
  -u ck_1234567890abcdef:cs_1234567890abcdef

Response:

[
  {
    "download_id": "abc123",
    "download_url": "https://example.com/?download_file=123&...",
    "product_id": 456,
    "product_name": "Digital Product",
    "download_name": "product-file.pdf",
    "order_id": 789,
    "order_key": "wc_order_xyz",
    "downloads_remaining": "unlimited",
    "access_expires": "never",
    "access_expires_gmt": "never",
    "file": {
      "name": "Product File",
      "file": "https://example.com/wp-content/uploads/product-file.pdf"
    }
  }
]

Error Handling

Invalid Customer ID

{
  "code": "woocommerce_rest_customer_invalid_id",
  "message": "Invalid customer ID.",
  "data": {
    "status": 404
  }
}

Email Already Exists

{
  "code": "registration-error-email-exists",
  "message": "An account is already registered with your email address. Please log in.",
  "data": {
    "status": 400
  }
}

Invalid Email Format

{
  "code": "rest_invalid_param",
  "message": "Invalid parameter(s): email",
  "data": {
    "status": 400,
    "params": {
      "email": "Email is not a valid email address."
    }
  }
}

Username Already Exists

{
  "code": "registration-error-username-exists",
  "message": "An account is already registered with that username. Please choose another.",
  "data": {
    "status": 400
  }
}

Security Considerations

Protecting Customer Data

Customer data includes personal information. Ensure you:

Use HTTPS for all API requests
Store API credentials securely
Limit API key permissions to necessary operations
Comply with GDPR and other privacy regulations
Never log or display customer passwords

When working with customer data:

Data Access: Customers have the right to access their data
Data Portability: Allow customers to export their data
Right to Erasure: Implement customer data deletion
Consent: Ensure proper consent for data processing

Password Security

// Good - Strong password with complexity
const customer = {
  email: 'user@example.com',
  password: 'StrongP@ssw0rd123!'
};

// Bad - Weak password
const customer = {
  email: 'user@example.com',
  password: 'password'
};

REST API

Store API

PHP APIs

Core Classes

Customers REST API

Customers API

The Customer Object

Customer Properties

List All Customers

Query Parameters

Example Response

Retrieve a Customer

Create a Customer

Required Fields

Important Fields

Update a Customer

Delete a Customer

Parameters

Batch Update Customers

Common Use Cases

Find Customer by Email

Search Customers

Update Customer Address

Get Customer Orders

Reset Customer Password

Customer Downloads

List Customer Downloads

Error Handling

Invalid Customer ID

Email Already Exists

Invalid Email Format

Username Already Exists

Security Considerations

Protecting Customer Data

Password Security

Next Steps

Orders API

Products API

​Customers API

​The Customer Object

​Customer Properties

​List All Customers

​Query Parameters

​Example Response

​Retrieve a Customer

​Create a Customer

​Required Fields

​Important Fields

​Update a Customer

​Delete a Customer

​Parameters

​Batch Update Customers

​Common Use Cases

​Find Customer by Email

​Search Customers

​Update Customer Address

​Get Customer Orders

​Reset Customer Password

​Customer Downloads

​List Customer Downloads

​Error Handling

​Invalid Customer ID

​Email Already Exists

​Invalid Email Format

​Username Already Exists

​Security Considerations

​Protecting Customer Data

​GDPR Compliance

​Password Security

​Next Steps

Orders API

Products API

Customers API

The Customer Object

Customer Properties

List All Customers

Query Parameters

Example Response

Retrieve a Customer

Create a Customer

Required Fields

Important Fields

Update a Customer

Delete a Customer

Parameters

Batch Update Customers

Common Use Cases

Find Customer by Email

Search Customers

Update Customer Address

Get Customer Orders

Reset Customer Password

Customer Downloads

List Customer Downloads

Error Handling

Invalid Customer ID

Email Already Exists

Invalid Email Format

Username Already Exists

Security Considerations

Protecting Customer Data

GDPR Compliance

Password Security

Next Steps