Customers
The Customers resource provides full CRUD for WooCommerce customers (WordPress users with WC data).
Visibility policy in 1.1.2
The default role remains customer. Configure customer-like roles with an immutable policy:
'customerRoles' => new \BetterRoute\Integration\Woo\CustomerRolePolicy(
allowedRoles: ['customer', 'subscriber'],
excludedRoles: [],
allowPrivilegedRoles: false,
),
The same policy covers list, detail, update and delete. Request role accepts a slug,
CSV or array but can only narrow the configured set. Administrative multi-role users,
direct privileged capability entries and superadmins are excluded unless explicitly
enabled in trusted configuration. Native mutation capabilities still apply. Creation
assigns customer only and cannot create an object excluded by the configured role policy.
SQL restrictions precede pagination/counting. Arbitrary dynamic capability filters can still remove objects after SQL counting, so third-party filters can shorten pages. Known authorization/session/application-password metadata is blocked on write and omitted on read. Custom third-party authorization metadata needs an application allowlist.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /woo/customers | List customers |
| GET | /woo/customers/{id} | Get customer |
| POST | /woo/customers | Create customer |
| PUT / PATCH | /woo/customers/{id} | Update customer |
| DELETE | /woo/customers/{id} | Delete customer |
List query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
fields | string | default set | Comma-separated field names |
role | string|array | — | Filter by role (comma-separated) |
email | string | — | Exact email match |
search | string | — | Wildcard search on display name |
sort | string | -registered_date | Sort field, prefix - for DESC |
page | int | 1 | Page number |
per_page | int | 20 | Items per page (max 100) |
Allowed sort fields: registered_date, id, email, display_name
Available fields
List defaults: id, email, first_name, last_name, display_name, role, date_created
All fields: id, email, first_name, last_name, display_name, role, username, date_created, date_modified, billing, shipping, is_paying_customer, avatar_url, orders_count, total_spent, meta_data
Since 1.0.0: orders_count and total_spent are no longer in the list defaults — each is a per-customer order query, so including them by default made list an N+1. They are still returned by get and by list when requested explicitly via ?fields=. total_spent is serialized as a decimal string; orders_count stays an integer.
Create / Update payload
{
"email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe",
"username": "janedoe",
"password": "securepassword123",
"billing": {
"first_name": "Jane",
"last_name": "Doe",
"address_1": "456 Oak Ave",
"city": "Portland",
"state": "OR",
"postcode": "97201",
"country": "US",
"email": "jane@example.com",
"phone": "+1234567890"
},
"shipping": { },
"meta_data": [
{ "key": "preferred_language", "value": "en" }
]
}
Notes
-
Customer list defaults omit metadata: select
fields=meta_dataexplicitly there. Detail and create/update responses can include filtered public metadata by default. Apply application-specific filtering where third-party metadata needs narrower disclosure. -
Updates use
WooCustomerUpdateInput, without username and requiring a non-empty payload. -
emailis required on create and must be unique. (v1.1.0) the create route's OpenAPI schema isWooCustomerCreateInput, which marksemailas required. -
usernameis create-only. It cannot be changed after creation. (v1.1.0) sendingusernamein an update payload returns400 validation_failed; previously it was silently ignored. -
passwordis write-only. It is never returned in responses. -
Address fields (billing/shipping): first_name, last_name, company, address_1, address_2, city, state, postcode, country, email, phone.
-
Delete uses
wp_delete_user()and permanently removes the WordPress user.
Since 1.1.0:
- The whole payload is validated before persistence:
email,first_name,last_name,username, andpasswordmust be strings, unknown keys insidebilling/shippingreturn400 validation_failed(field not allowed), and address values must be strings (no silent casting). The OpenAPI address schema declaresadditionalProperties: falseto match. - List sorting always appends an
IDtie-breaker, so pagination is deterministic when many customers share the same sort value.
Since 1.0.0:
DELETE /customers/{id}works in the REST context: the library loadswp-admin/includes/user.phpbefore callingwp_delete_user()(that file is not auto-loaded on REST requests, so the endpoint previously failed silently). Thedelete_usercapability check still applies.- Invalid input rejected by a WooCommerce CRUD setter (e.g. an invalid email via
WC_Customer::set_email(), aWC_Data_Exception) is returned as400, not500.
v0.3.0 restrictions
- Default customer-only policy: 1.1.2 permits explicitly configured customer-like roles as described above. Out-of-policy users return 404 from detail/mutations and are filtered from lists.
- Capability checks layered on top of the configured
permissions:createrequirescreate_usersupdaterequiresedit_userdeleterequiresdelete_user
- Protected meta keys (
_...) are not returned and not writable by default.