Skip to Content
StoreOSv0.31.0
ThemesContexts

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

PageURLDocument page
Account/accountaccount
Sign in/account/loginlogin
Orders/account/ordersorders
Profile/account/profileprofile
Cart/cartcart
Wishlist/wishlistwishlist
Track order/track-order, /track-order/:idtrack-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:

ObjectContents
page_titleAccount, Sign in, Orders, Profile, Cart, Wishlist or Track order
order_idOn /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.

WhatRequest
Send a sign-in codePOST /api/v1/auth/otp/send with { "phoneNumber" }
Verify itPOST /api/v1/auth/otp/verify with { "phoneNumber", "otp", "name"? } → { accessToken, user }
Who is signed inGET /api/v1/auth/me
Update the namePATCH /api/v1/auth/profile with { "name" }
Sign outPOST /api/v1/auth/logout
OrdersGET /api/v1/orders?page=1&limit=10 → { nodes, meta }
One orderGET /api/v1/orders/:id (works signed out, for order tracking)
WishlistGET /api/v1/wishlist → { nodes, productIds } (live, published products, newest first)
Save or remove a productPOST /api/v1/wishlist/:productId/toggle → { productId, saved }
Add products saved before sign-inPOST /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 a data-saved attribute 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:

MemberDoes
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.

On this page