Contact accounts

Contacts give your storefront contact accounts: registration, login, password reset, a profile, and saved addresses. All routes live under /v1/api/contacts, with an identical alias at /v1/api/customers for integrations built before the rename. Contacts are part of every store, so there is no module to enable first.

Alias: /v1/api/customers#

Every route below is also served, unchanged, at the equivalent /v1/api/customers/... path (for example POST /v1/api/customers/register alongside POST /v1/api/contacts/register). Request and response shapes are identical on both. This alias is permanent, not a deprecation window: existing integrations never need to migrate, though new integrations should use /v1/api/contacts.

Two tokens, two headers#

Contact 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 contacts:write scope for all POST, PATCH, and DELETE endpoints and the contacts:read scope for the GET endpoints. A key minted before the rename carries customers:write / customers:read instead, and is still accepted. A missing scope returns 403 {"message":"Invalid ability provided."}.
2. Contact session token (required on contact-authenticated endpoints). POST /v1/api/contacts/register and POST /v1/api/contacts/login return a token string. Send it on subsequent requests in the X-Customer-Token header. A missing or invalid contact token returns 401 {"message":"Invalid customer token."}.

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

Which endpoints need which:

Contact 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 contact's tokens).

The public contact object#

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

kind, company_name, registration_number, vat_id, and external_id are readable on every contact but not writable through register or PATCH /me: a storefront account cannot turn itself into a company contact. The merchant sets these fields from the client dashboard's Contacts pages.

Guest lifecycle#

Cart email capture in the Commerce module can create a contact 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 contact 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: