Customer accounts

The Customers module gives your storefront customer accounts: registration, login, password reset, a profile, and saved addresses. All routes live under /v1/api/customers and require the customers module to be enabled for your store; calling them without it returns 403 {"error": "Module not enabled: customers"}.

Two tokens, two headers#

Customer endpoints use a layered authentication model:

1. Tenant API key (always required). Every request carries your store's API key as Authorization: Bearer {api_key}, exactly like the rest of the storefront API. The key needs the customers:write scope for all POST, PATCH, and DELETE endpoints and the customers:read scope for the GET endpoints. A missing scope returns 403 {"message":"Invalid ability provided."}.
2. Customer session token (required on customer-authenticated endpoints). POST /v1/api/customers/register and POST /v1/api/customers/login return a token string. Send it on subsequent requests in the X-Customer-Token header. A missing or invalid customer token returns 401 {"message":"Invalid customer token."}.

The two headers are independent and both required on customer-authenticated routes:

Which endpoints need which:

Customer session tokens do not expire on a timer. They are revoked by POST /logout (one token) and by a successful password reset (all of the customer's tokens).

The public customer object#

Customer-facing endpoints return this shape (internal fields such as is_guest, type, and customer_group_id are never exposed on the storefront API):

Guest lifecycle#

Cart email capture in the Commerce module can create a customer row with only an email and no password (a guest). This matters in three places:

• Registration upgrades guests. Registering with an email that belongs to a guest row upgrades that row in place: same id, order history preserved. Only an email that belongs to a real (non-guest) account fails with 422 "Email already registered.".
• Guests cannot log in. They have no password, so login fails with the generic 422 "Invalid credentials.".
• Password reset also upgrades. Completing a reset sets a password, marks the account non-guest, and sets email_verified_at if it was unset. This is a second path from guest checkout to a full account.

Rate limits#

All customer endpoints share the storefront limit of 120 requests per minute per store (429 with a Retry-After header when exceeded). The four credential endpoints (register, login, forgot-password, reset-password) carry an additional limit of 10 requests per minute per client IP to slow brute force attempts.

Errors#

All error envelopes are the standard storefront shapes: