Shopper pages
Account, sign-in, orders, profile, cart, wishlist and order tracking in a StoreOS Fluid theme, and how to load the shopper's data in the browser.
Shopper pages show one shopper's own things: their account, orders, bag and saved items. StoreOS renders them with its own design until your theme takes one over.
Routes
| Page | URL | Document page |
|---|---|---|
| Account | /account | account |
| Sign in | /account/login | login |
| Orders | /account/orders | orders |
| Profile | /account/profile | profile |
| Cart | /cart | cart |
| Wishlist | /wishlist | wishlist |
| Track order | /track-order, /track-order/:id | track-order |
Taking a page over
A shopper page renders with your theme when the theme has layout/<page>.fluid or widgets in pages.<page>. Otherwise StoreOS renders it, so you can take over one page at a time.
{
"pages": {
"login": ["main-login"],
"orders": ["main-orders"],
"cart": ["main-cart"]
}
}storeos theme dev shows a note on a shopper page your theme doesn't take over yet.
Data
The server knows nothing about who is visiting, so these pages get shop-wide data only:
| Object | Contents |
|---|---|
page_title | Account, Sign in, Orders, Profile, Cart, Wishlist or Track order |
order_id | On /track-order/:id, the order number from the URL; empty otherwise |
Plus the data on every page. StoreOS never indexes these pages: their SEO tags say noindex, nofollow.
The shopper's own data loads in the browser from the Storefront REST API at shop.api_url. Send the store's x-tenant header (shop.uid) with every call.
| What | Request |
|---|---|
| Send a sign-in code | POST /api/v1/auth/otp/send with { "phoneNumber" } |
| Verify it | POST /api/v1/auth/otp/verify with { "phoneNumber", "otp", "name"? } → { accessToken, user } |
| Who is signed in | GET /api/v1/auth/me |
| Update the name | PATCH /api/v1/auth/profile with { "name" } |
| Sign out | POST /api/v1/auth/logout |
| Orders | GET /api/v1/orders?page=1&limit=10 → { nodes, meta } |
| One order | GET /api/v1/orders/:id (works signed out, for order tracking) |
| Wishlist | GET /api/v1/wishlist → { nodes, productIds } (live, published products, newest first) |
| Save or remove a product | POST /api/v1/wishlist/:productId/toggle → { productId, saved } |
| Add products saved before sign-in | POST /api/v1/wishlist/merge with { "productIds" } |
Signed-in calls send Authorization: Bearer <accessToken>.
The wishlist is kept in the shopper's account, so only signed-in shoppers can save products. You rarely need to call these endpoints yourself: StoreOS adds a wishlist helper for you (below).
Wishlist buttons
content_for_header includes a small StoreOS script that runs your wishlist buttons. Mark a button with the product's ID and it works on any page:
<button type="button" data-storeos-wishlist="{{ product.id }}" aria-label="Wishlist">♡</button>
{% comment %} Optional: number of saved products, e.g. in the header {% endcomment %}
<a href="/wishlist">Wishlist <span data-storeos-wishlist-count></span></a>- A click saves the product, and the next click removes it. Every button for the same product updates together.
- The button gets
aria-pressed="true"and adata-savedattribute while the product is saved, so you can style it:[data-storeos-wishlist][data-saved] { color: var(--color-primary); }. aria-busy="true"is set while the request is in flight; further clicks on that product wait.- A signed-out shopper goes to
/account/login?redirectTo=<this page>and comes back after signing in.
For your own markup, use window.StoreOS.wishlist and listen for the storeos:wishlist event:
| Member | Does |
|---|---|
has(productId) | Whether the product is saved |
toggle(productId) | Saves or removes; resolves to true when saved |
productIds() | Saved product IDs, newest first |
signedIn() | Whether a shopper is signed in |
sync() | Re-applies the state to [data-storeos-wishlist] buttons added after page load |
refresh() | Reloads the list from the account |
<script>
document.addEventListener("storeos:wishlist", (event) => {
// event.detail: { productIds, signedIn, ready }
console.log("saved", event.detail.productIds.length);
});
</script>To build your own /wishlist page, load the products with GET /api/v1/wishlist (above) or leave the page to StoreOS.
Share sign-in with StoreOS
Keep the token in the cookie storeos__auth_<shop.uid>. StoreOS's own pages and the wishlist helper use the same cookie, so a shopper stays signed in when they move between your pages and StoreOS's (such as checkout). The wishlist is stored in the account, so it's the same on every page and device.
Example
{% comment %} layout/theme.fluid, inside <body> {% endcomment %}
<script type="application/json" id="store">
{"tenant": "{{ shop.uid }}", "api": "{{ shop.api_url }}"}
</script>{% comment %} widgets/main-orders.fluid {% endcomment %}
<section class="orders" data-orders>
<h1>{{ page_title }}</h1>
<ul></ul>
</section>
<script>
(async () => {
const { tenant, api } = JSON.parse(document.getElementById("store").textContent);
const token = document.cookie.match(new RegExp(`storeos__auth_${tenant}=([^;]+)`))?.[1];
if (!token) return location.replace(`/account/login?redirectTo=${location.pathname}`);
const res = await fetch(`${api}/api/v1/orders?page=1&limit=10`, {
headers: { "x-tenant": tenant, Authorization: `Bearer ${token}` },
});
const { nodes } = await res.json();
document.querySelector("[data-orders] ul").innerHTML = nodes
.map((order) => `<li>#${order.invoiceUID} · ${order.invoiceStatus}</li>`)
.join("");
})();
</script>In storeos theme dev, shop.api_url is empty: the dev server forwards /api/… to your store, so the same code works locally.