Methods

How to read this page

Each method below maps to a StoreOS REST route. The package calls the API, adds your tenant UID (x-tenant), and returns typed data.

Methods with a icon require a logged-in customer (JWT on the client).

Catalog

What is the catalog?

The catalog is everything a customer can browse before buying — your products (items for sale) and collections (groups of products, like "Summer sale" or "New arrivals"). You manage catalog data in the StoreOS console; your storefront app reads it through these methods to build shop pages, product detail pages, and filters.

Typical pages you build: home, /shop, /product/[handle], collection landing pages.

getTenant()

Returns your store settings — store name, delivery charges, support contact, legal policies (privacy, refund, terms), social links, and theme data.

Use this on checkout to calculate delivery fees, on the footer for support info, and anywhere you need store-wide config.

const tenant = await store.getTenant();
// tenant.name, tenant.charges, tenant.legalPolicies, …

getProducts(params?)

Returns a paginated list of published products for your store. Supports search, pagination, and filtering by collection.

Use this for shop listing pages, search results, and "related products" grids.

const { nodes, meta } = await store.getProducts({
  page: 1,
  limit: 24,
  search: "shirt",
  collectionIds: ["collection-id"],
});

getProduct({ handle }) · getProduct({ id }) · getProductByHandle() · getProductById()

Returns one product with full detail — title, descriptions, price, images (gallery, thumbnail), variants, and status.

• handle — URL-friendly slug (e.g. linen-shirt). Use on /product/[handle] routes.
• id — internal product ID from StoreOS. Use when you already have the ID from a list or cart.

const product = await store.getProduct({ handle: "linen-shirt" });
const product = await store.getProduct({ id: "674a1b2c3d4e5f6789012345" });

getCollections(params?)

Returns a paginated list of collections — named groups you use to organize the catalog (e.g. "Best sellers", "Electronics").

Use this for navigation menus, homepage sections, and collection index pages.

const { nodes: collections, meta } = await store.getCollections({
  page: 1,
  search: "sale",
});

getCollection(id)

Returns one collection by ID. Use when you land on a collection page and need its name/description, or before filtering getProducts({ collectionIds: [id] }).

const collection = await store.getCollection("collection-id");

Auth

What is auth?

Auth lets customers create an account, sign in, and access their profile and order history. StoreOS issues a JWT (accessToken) after login, register, or phone OTP. The SDK keeps it in memory; your app should save it (cookie, localStorage) and restore with setAccessToken().

Typical pages you build: /auth, /auth/phone, /dashboard, account settings.

register(input)

Creates a new customer account (name, email and/or phone, password). Returns accessToken + user and logs the customer in on the client.

const { accessToken, user } = await store.register({
  name: "Jane",
  email: "jane@example.com",
  password: "secure-password",
});

login(input)

Signs in an existing customer with email or phone + password. Returns accessToken + user.

await store.login({ user: "jane@example.com", password: "secure-password" });

getMe()

Returns the currently logged-in customer — name, email, phone, shipping address. Fails if there is no valid token.

const me = await store.getMe();

updateProfile(input)

Updates the logged-in customer's name, phone, or shipping address.

await store.updateProfile({ name: "Jane Doe", phoneNumber: "+8801…" });

changePassword(input)

Changes password for the logged-in customer. Requires current password.

await store.changePassword({ currentPassword: "…", newPassword: "…" });

logout()

Tells the API the session ended. Your app should also clear the saved token. JWTs are stateless — clearing the client token is what actually signs the user out in the browser.

await store.logout();
store.setAccessToken(undefined);

sendOtp(input) · verifyOtp(input)

Phone OTP login (common in Bangladesh). sendOtp texts a 4-digit code to the customer's phone. verifyOtp checks the code and returns accessToken + user.

New customers must pass name on verify. Check isNewCustomer from sendOtp to show a name field.

await store.sendOtp({ phoneNumber: "+8801XXXXXXXXX" });

await store.verifyOtp({
  phoneNumber: "+8801XXXXXXXXX",
  otp: "1234",
  name: "Jane", // required for new customers
});

Checkout

What is checkout?

Checkout turns a cart (items the customer wants) into a placed order on StoreOS. Your app owns the cart UI; these methods validate coupons and submit the order with shipping address, delivery area, and payment method.

Typical pages you build: /checkout, order confirmation.

verifyCoupon(input)

Checks whether a discount code is valid for the current cart. You must send the coupon code and the line items (product ID, variant ID, quantity) so StoreOS can calculate the discount.

const coupon = await store.verifyCoupon({
  code: "SAVE10",
  lineItems: [{ productId: "…", variantId: "…", quantity: 2 }],
});

if (coupon.valid) {
  console.log(coupon.discountAmount);
}

createOrder(input)

Places an order — the main checkout action. Sends line items, shipping address, payment method (COD or ONLINE), delivery area, and optional coupon.

• Guest checkout: no token needed; customer details go in the order input.
• Logged-in: pass the customer's token; order links to their account.
• May return authToken for guests so they can track the order right away.

const { order, authToken } = await store.createOrder({
  lineItems: [{ productId: "…", variantId: "…", quantity: 2 }],
  shippingAddress: { caption: "House 12, Road 5, Dhaka", latitude: 23.8, longitude: 90.4 },
  paymentMethod: "COD",
  deliveryArea: "DHAKA",
  couponCode: "SAVE10",
});

Orders

What are orders?

After checkout, StoreOS creates an order (invoice) with a unique invoiceUID. Customers can view order status, track shipment, and cancel when allowed. Logged-in customers see their full history.

Typical pages you build: /dashboard/orders, /track-order/[orderId], order confirmation.

getMyOrders(params?)

Returns a paginated list of orders for the logged-in customer. Filter by date range or status.

const { nodes: orders } = await store.getMyOrders({
  page: 1,
  limit: 10,
  status: "PENDING",
});

getOrder(orderId)

Returns one order by its invoiceUID (the public order ID you show customers).

Does not require login — use for public order tracking ("Where is my order?") when the customer has the order ID.

const order = await store.getOrder("INV-2024-00123");

cancelOrder(orderId, reason?)

Cancels an order for the logged-in customer who placed it. Optional cancellation reason.

await store.cancelOrder("INV-2024-00123", "Changed my mind");

Session

These methods manage the customer JWT on the SDK instance. They do not call the API (except logout).

getAccessToken() · setAccessToken(token?)

Read or restore the JWT. After login, save getAccessToken() in your app; on the next visit, call setAccessToken(saved) before getMe() or getMyOrders().

const token = store.getAccessToken();
store.setAccessToken(tokenFromCookie);

Pagination

List methods (getProducts, getCollections, getMyOrders) return:

{
  nodes: T[],      // items for this page
  meta: {
    totalCount,    // total items across all pages
    currentPage,
    hasNextPage,
    totalPages,
  }
}

Use meta.hasNextPage and page + 1 for "Load more" or next-page links.

Pass limit: -1 to fetch every item in a single response — hasNextPage is false and totalPages is 1.

Errors

Failed API calls throw StoreFrontApiError with HTTP status, message, and response body:

import { StoreFront, StoreFrontApiError } from "@storeos/storefront-client";

try {
  await store.getProduct({ handle: "sold-out" });
} catch (error) {
  if (error instanceof StoreFrontApiError) {
    // 404 = not found, 401 = not logged in, 400 = validation error
    console.error(error.status, error.body);
  }
}

Types

Import shapes for props, forms, and API responses:

import type {
  Product,
  Collection,
  Order,
  Tenant,
  StorefrontUser,
  CreateOrderInput,
  PaginatedResponse,
} from "@storeos/storefront-client";