Storefront
Customer accounts
Sign up, sign in with a password or Google, sign out, reset a password, keep addresses.
Shoppers can have an account on your store. It is separate from your team's Mercestack logins — a shopper never becomes a member of your workspace — and it works the same on the hosted storefront and on your own site through the API.
Every sign-in returns a customer session: a token you send as X-Mercestack-Customer-Token next to your publishable key. The JavaScript SDK stores it for you. Orders are matched by email, so a new account sees everything bought with its address before it existed.
- Passwords are at least 8 characters. Five wrong attempts lock sign-in for that email for 15 minutes.
- Signing out revokes the session everywhere, not just on this device.
- A reset link works once, expires in 30 minutes, and stops working if the password changes first.
- Every account is linked to a customer in your CRM, created if needed.
Create an account
/v1/storefront/customer/registerCreates the account and signs it in. Returns 409 if the email already has an account — send the shopper to sign in instead.
Body
emailstringrequired- Shopper's email.
passwordstringrequired- At least 8 characters.
namestringrequired- Full name.
phonestring- Optional.
curl -X POST https://api.mercestack.com/v1/storefront/customer/register \
-H "Authorization: Bearer pk_test_…" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"a-long-password","name":"Bola Adeyemi"}'{
"token": "eyJhbGciOi…",
"customer": {
"id": "0b1d6e0e-…",
"email": "[email protected]",
"name": "Bola Adeyemi",
"phone": "+2348030000000",
"emailVerified": true,
"hasPassword": true,
"google": false,
"addresses": [],
"createdAt": "2026-09-27T10:00:00.000Z"
}
}Sign in
/v1/storefront/customer/loginEmail and password. A wrong password and an unknown email give the same answer, so the endpoint can't be used to find out who shops with you.
Body
emailstringrequired- Shopper's email.
passwordstringrequired- Their password.
curl -X POST https://api.mercestack.com/v1/storefront/customer/login \
-H "Authorization: Bearer pk_test_…" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"a-long-password"}'{ "token": "eyJhbGciOi…", "customer": { … } }Sign in with Google
/v1/storefront/customer/googleCreates the account on first use and signs it in. Send either the idToken from Google Identity Services, or an authorization code with its PKCE codeVerifier and redirectUri. The token's audience must be your platform's Google client.
Body
idTokenstring- A Google ID token.
codestring- Or: an OAuth authorization code…
codeVerifierstring- …its PKCE verifier…
redirectUristring- …and the redirect URI it was issued for.
curl -X POST https://api.mercestack.com/v1/storefront/customer/google \
-H "Authorization: Bearer pk_test_…" \
-H "Content-Type: application/json" \
-d '{"idToken":"eyJhbGciOiJSUzI1NiIs…"}'{ "token": "eyJhbGciOi…", "customer": { … }, "verifyUrl": "https://…" }Sign out
/v1/storefront/customer/logoutEnds every session the account has. The token you sent stops working immediately.
curl -X POST https://api.mercestack.com/v1/storefront/customer/logout \
-H "Authorization: Bearer pk_test_…" \
-H "X-Mercestack-Customer-Token: <session>"{ "signedOut": true }Send a reset link
/v1/storefront/customer/password/forgotEmails a link to <your store>/account/reset?token=…. Always answers the same way, whether or not the email has an account.
Body
emailstringrequired- Account email.
curl -X POST https://api.mercestack.com/v1/storefront/customer/password/forgot \
-H "Authorization: Bearer pk_test_…" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]"}'{ "sent": true, "previewUrl": null }Set a new password
/v1/storefront/customer/password/resetTakes the token from the reset link. Signs the shopper in and ends their other sessions.
Body
tokenstringrequired- From the reset link.
passwordstringrequired- The new password.
curl -X POST https://api.mercestack.com/v1/storefront/customer/password/reset \
-H "Authorization: Bearer pk_test_…" \
-H "Content-Type: application/json" \
-d '{"token":"eyJhbGciOi…","password":"a-new-password"}'{ "token": "eyJhbGciOi…", "customer": { … } }Get the signed-in shopper
/v1/storefront/customer/meProfile and saved addresses. A shopper signed in with an emailed link but no account gets id: null.
curl https://api.mercestack.com/v1/storefront/customer/me \
-H "Authorization: Bearer pk_test_…" \
-H "X-Mercestack-Customer-Token: <session>"{
"id": "0b1d6e0e-…",
"email": "[email protected]",
"name": "Bola Adeyemi",
"phone": "+2348030000000",
"emailVerified": true,
"hasPassword": true,
"google": false,
"addresses": [],
"createdAt": "2026-09-27T10:00:00.000Z"
}Update the profile
/v1/storefront/customer/meName and phone. Email changes aren't supported yet.
Body
namestring- Full name.
phonestring | null- Phone, or null to clear it.
curl -X PATCH https://api.mercestack.com/v1/storefront/customer/me \
-H "Authorization: Bearer pk_test_…" \
-H "X-Mercestack-Customer-Token: <session>" \
-H "Content-Type: application/json" \
-d '{"phone":"+2348030000000"}'{
"id": "0b1d6e0e-…",
"email": "[email protected]",
"name": "Bola Adeyemi",
"phone": "+2348030000000",
"emailVerified": true,
"hasPassword": true,
"google": false,
"addresses": [],
"createdAt": "2026-09-27T10:00:00.000Z"
}Add an address
/v1/storefront/customer/me/addressesSaves an address for checkout. Setting isDefault makes it the only default. Up to 20 per account.
Body
namestringrequired- Recipient.
line1stringrequired- Street address.
citystringrequired- City.
countrystringrequired- Country name.
labelstring- "Home", "Office".
line2, state, postalCode, phonestring- Optional.
isDefaultboolean- Use at checkout by default.
curl -X POST https://api.mercestack.com/v1/storefront/customer/me/addresses \
-H "Authorization: Bearer pk_test_…" \
-H "X-Mercestack-Customer-Token: <session>" \
-H "Content-Type: application/json" \
-d '{"name":"Bola Adeyemi","line1":"1 Marina","city":"Lagos","country":"Nigeria","isDefault":true}'[ { "id": "…", "label": "Home", "city": "Lagos", "isDefault": true, … } ]Remove an address
/v1/storefront/customer/me/addresses/:idReturns the addresses that are left.
curl -X DELETE https://api.mercestack.com/v1/storefront/customer/me/addresses/ADDRESS_ID \
-H "Authorization: Bearer pk_test_…" \
-H "X-Mercestack-Customer-Token: <session>"[]In React
import { useCustomer } from "@mercestack/commerce-react";
function Account() {
const { customer, signedIn, login, logout, loading } = useCustomer();
if (loading) return null;
if (!signedIn) return <SignInForm onSubmit={login} />;
return <button onClick={logout}>Sign out {customer!.name}</button>;
}