| <store name>` from the home page's metadata. | Page | `<title>` | Description | Share image (`og:image`) | |---|---|---|---| | Home | The landing page's `seo_title` (`getHomeSeo()`), else `brand_name` (or `name`) | Landing `seo_description`, else `description`, else `top_bar_text` | Landing `seo_image`, else `hero_images[0]`, else the logo | | Product | `seo_title`, else the name | `seo_description`, else `description`, else the name | `seo_image`, else `image_urls[0]` | | Category | `seo_title`, else the name | `seo_description`, else the store `description`, else "Shop <name> at <store>." | `seo_image`, else the category `image`, else `hero_images[0]` | | Brand | The brand page's `seo_title`, else the brand name | The brand page's `seo_description`, else "Shop <brand> at <store>." | The brand page's `seo_image`, else the brand logo | | Blog post | `seo_title` | `seo_description` | `seo_image` (all three already defaulted by the API) | Where the Blanxer-hosted storefront differs: its product `<title>` is the name (`seo_title` only for `og:title`), its category description falls back to `top_bar_text`, and its brand title has no brand-name fallback (the package's fallback is an improvement). - Home SEO comes from the store's landing page (`GET /public/landing/<store_id>`, read by `getHomeSeo()`). Only stores on a page-builder plan have one; otherwise the store name and description are used. - The brand page's SEO fields come from `GET /brand/public/products/<store_id>/<slug>` as `brand.page.seo_title`, `seo_description`, `seo_image`. - Every page: `og:site_name` = the store name, `og:type` (`website`, `product`, `article`), `twitter:card` = `summary_large_image`, and a canonical URL `<origin><path>` without query strings (except `/blogs?category=`). - `noindex` on `/cart`, `/checkout`, `/payment/success`, `/payment/failed`, `/track/[id]`, `/search`, and blog posts with `no_index`. - On stores without a landing page, confirm the home title and description (the store name and description) with the merchant. To improve the text, use the MCP: `blanxer_audit_seo`, then `blanxer_update_product_status_seo`, `blanxer_bulk_update_products`, `blanxer_bulk_update_categories_seo`, `blanxer_update_brand`. Confirm bulk changes first (rule 13). See [MCP for your website](https://developers.blanxer.com/api-docs/mcp-for-website.md). ## JSON-LD Add structured data with the package's `productJsonLd`, `organizationJsonLd` and `breadcrumbJsonLd`, in a `<script type="application/ld+json">`. **Product** (product pages), from real data only: - `@type: Product`, `@id: <url>#product`, `name`, `url`, `description` (`seo_description` or the name), `image` (all `image_urls`); - `offers`: `@type: Offer`, `price` (first variant's price, else the product's), `priceCurrency: NPR`, `availability` (`InStock` when `continue_selling`, or any stock), `itemCondition: NewCondition`, `seller` = the store; - `sku` and `gtin` (barcode) when present, `brand` when the product has one, `category` from the first matching category name; - `aggregateRating` only when `review_count > 0`: `ratingValue` = `total_rating / review_count` (the average, 1–5), `reviewCount`. (The Blanxer storefront puts the raw sum in `ratingValue`; don't copy that.) - `review` entries only for real reviews. **Organization** (home): `name`, `url`, `logo`, and `sameAs` with the `social` links that are set. **BreadcrumbList** (product, category, brand): Home → Category or Brand → Product. Never add placeholder ratings, prices or reviews (rule 8). ## Search Console verification 1. The merchant adds the site in [Google Search Console](https://search.google.com/search-console) as a **URL-prefix** property (`https://mystore.com/`) and picks **HTML tag**. They copy the tag or just its `content` value. 2. You call `blanxer_set_site_verification { google_verification_code: "<the tag or the content value>" }` through the MCP. Blanxer stores it in the `meta_tags` plugin as `{n: "google-site-verification", c: "<code>"}`. 3. The site renders every `meta_tags` entry as `<meta name={n} content={c}>` on the home page. `verificationMetadata(store)` from the package returns it as Next.js `metadata.verification` / `metadata.other`. 4. Wait about a minute for the caches, check the tag is in the page source, then click **Verify**. 5. Submit `https://<site>/sitemap.xml` under **Sitemaps**. A **Domain** property (verified with a DNS TXT record) works too: the merchant adds the TXT record in their own Cloudflare DNS. Then no meta tag is needed. ## Google Analytics, Tag Manager and Clarity The ids come from `check_domain.plugins`, an array of `{name, details}`: - `ga`: a GA4 id (`G-...`); - `gtm`: a Tag Manager id (`GTM-...`); - `clarity`: a Microsoft Clarity id. Set or change GA/GTM with `blanxer_set_site_verification { ga_id }` or `{ gtm_id }`. The package's `<Pixel>` loads GA4, GTM, Clarity and the Meta Pixel from these plugins, each only when its id is present and after the page is interactive. Never hardcode an id in the site. ## Meta Pixel and Conversions API - **Pixel:** when `plugins` has `fb_pixel`, load Meta's `fbevents.js` with that id and track `PageView` on every route change. - **Conversions API relay:** when `plugins` has `meta_capi` (its `details` is just `true`; the access token stays on Blanxer's server), every event is also sent to Blanxer, which forwards it to Meta. The relay goes through Blanxer's domain, so ad blockers don't drop it. The package's `Pixel` component and `trackEvent` do both. ### Events | Event | When | `custom_data` | |---|---|---| | `ViewContent` | Product page opens | `content_ids: [product _id]`, `content_name`, `content_type: 'product'`, `value`, `currency: 'NPR'` | | `AddToCart` | Add to cart | `content_ids: ['<product>_<variant>' or '<product>']`, `content_name`, `content_type`, `value`, `currency` | | `InitiateCheckout` | Checkout opens with lines | `content_ids`, `content_type`, `value`, `currency`, `num_items` | | `Purchase` | Order placed (COD) / paid (online) | `content_ids`, `content_type`, `value`, `currency`, `num_items` | `content_ids` must match the feed's `g:id`: `<product_id>_<variant_id>` for a variant line, the product `_id` otherwise. Otherwise Meta's catalog ads can't match events to products. ### The relay call ```http POST /public/meta-event/<store_id> Content-Type: application/json { "event_name": "AddToCart", "event_id": "<uuid, the same one passed to fbq as eventID>", "event_source_url": "https://mystore.com/product/pashmina-shawl", "fbp": "<_fbp cookie>", "fbc": "<_fbc cookie>", "custom_data": { "content_ids": ["..._..."], "content_type": "product", "value": 2500, "currency": "NPR" } } ``` - `event_name` is one of `ViewContent`, `AddToCart`, `InitiateCheckout`, `Purchase`. Add `email` and `phone` only for `Purchase`. - `custom_data` keeps only `value`, `currency`, `content_type`, `content_ids` (≤ 200), `contents` and `num_items`. Other keys, such as `content_name`, are dropped by the relay (the browser Pixel still gets them). - A valid event always gets `{"success": true}`: also when the store has no `meta_capi`, and when forwarding to Meta fails. A malformed body is HTTP 400 (validation error). - Limit: 100 per minute per IP. - Send it from the **browser** with `fetch(..., { keepalive: true })` and don't wait for it. Blanxer forwards the caller's IP and user agent to Meta, so a server-side call would report the Worker instead of the shopper. ### Purchase without double counting - The checkout creates one `event_id` per order and sends it in the order's `meta` block with `fbp`, `fbc` and `event_source_url`. - **COD:** Blanxer's server sends the CAPI `Purchase` when the order is created. The browser fires only the Pixel `Purchase`, with the same `event_id`. - **Online payments:** `/payment/success` fires the Pixel and the relay with that `event_id`. - Meta dedupes on `event_id`. ## Register the product feed After the site link is saved: - **Meta Commerce Manager:** Catalog → Data sources → Data feed → scheduled feed from URL `https://api.blanxer.com/public/product-feed/<store_id>.xml`, hourly or daily. - **Google Merchant Center:** Products → Feeds → scheduled fetch of the same URL. Meta's and Google's crawlers fetch the feed from `api.blanxer.com` directly. That hasn't been checked against Cloudflare's bot rules yet, so after adding it, check the feed fetched without errors (Commerce Manager / Merchant Center shows the fetch status). `blanxer_get_store_context` returns the feed and sitemap URLs (`product_feed_url`, `sitemap_url`) only once a site link is saved. They arrive with the BlanxerAPI release of the MCP. ---  # Images and speed Most shoppers in Nepal browse on mid-range phones over mobile data. Image weight is the main reason a store site is slow. Every BlanxerAPI site must pass these targets before it is deployed: - **Lighthouse mobile ≥ 90** on the home page, a product page and `/checkout`; - **LCP < 2.5 s**. `npx blanxer-storefront check` measures them (see [Package](https://developers.blanxer.com/api-docs/package.md#cli)). ## Rule 11, in full **Optimise every image before it goes into the site.** - Use `npx blanxer-storefront images`: - resize to the largest size shown ×2 (hero 2560 px, banner 1600, card 800); - export AVIF + WebP at ~75 quality; - strip EXIF and location data; - use SVG for logos when available. - Never commit originals. - Load with `next/image`: each page's main (LCP) image gets `preload`, the rest load lazily with correct `sizes`. - **Product photos go into Blanxer through the MCP, never into the site.** - No autoplay video backgrounds or GIF banners unless the merchant insists after hearing the speed cost. - Fonts go through `next/font`, at most 2 families. ## Size per slot Export at twice the largest width the slot is shown at, so it stays sharp on high-density screens. | Slot | Shown at (CSS px, widest) | Export width | `sizes` example | |---|---|---|---| | Hero, full-width banner | 1280 | **2560** | `100vw` | | Banner, half-width promo, blog cover | 800 | **1600** | `(max-width: 768px) 100vw, 50vw` | | Product card, category tile, brand tile | 400 | **800** | `(max-width: 768px) 50vw, 25vw` | | Logo | — | **SVG** when there is one; else 2× the shown height | — | | Share image (`og:image`) | — | 1200 × 630, WebP or JPEG | — | Budget, enforced by the check command: - no file in `public/` over **300 KB**; - no file wider than **2560 px**; - no JPEG or PNG where WebP or AVIF fits (PNG stays fine for a logo with no SVG); - every image rendered through `next/image` with a width and height (or `fill` with `sizes`); - each page's main (LCP) image marked with `preload` (or `loading="eager"` + `fetchPriority="high"`); the check warns when no image is marked. ## Optimising a merchant's images The merchant sends a hero photo, banner art, a logo. Before any of it goes into the repo: ```bash npx blanxer-storefront images ./incoming ./public/images ``` It resizes, writes AVIF and WebP next to each other, strips metadata (EXIF, GPS) and prints a size report. Show the merchant a before/after table, for example: | Image | Original | AVIF | WebP | |---|---|---|---| | hero.jpg | 6.8 MB, 6000 px | 212 KB, 2560 px | 298 KB, 2560 px | | banner-sale.png | 2.1 MB, 3200 px | 96 KB, 1600 px | 141 KB, 1600 px | Delete the originals; never commit them (`./incoming` belongs in `.gitignore`). Options and defaults: see the package README. ## Loading images ```tsx import Image from 'next/image'; import hero from '@/public/images/hero.avif'; export function Hero() { return <Image src={hero} alt="New winter collection" preload sizes="100vw" placeholder="blur" />; } ``` - **One main image per page, marked with `preload`**: the largest image above the fold (usually the LCP element). Next.js 16 deprecates `priority`; use `preload`, or `loading="eager"` with `fetchPriority="high"`. Everything else loads lazily, which is `next/image`'s default. - Always give `sizes` for responsive images, or the browser downloads the widest file. - Write real `alt` text. Product images: the product name (and variant). - Keep the image config the starter ships with. It is set up for Cloudflare Workers. ## Product photos Product photos live in Blanxer. `image_urls` and variant `image_url` are absolute URLs on Blanxer's storage, often uploaded straight from a phone camera at full size. Never download them into the site. Load them through the package's loader, which asks a resize service for the width `next/image` needs: ```tsx import Image from 'next/image'; import { blanxerImageLoader } from '@blanxer-dev/storefront/next'; <Image loader={blanxerImageLoader} src={product.image_urls[0]} alt={product.name} width={800} height={800} sizes="(max-width: 768px) 50vw, 25vw" /> ``` The Blanxer-hosted storefront uses `https://wsrv.nl/?w=<width>&url=<image>` for thumbnails today. The package's loader does the same by default (WebP output, quality 75). `NEXT_PUBLIC_BLANXER_IMAGE_LOADER` switches it: `wsrv` (default), `cloudflare` (Cloudflare Image Transformations on the site's own zone, `/cdn-cgi/image/...`; the merchant must turn Transformations on in Cloudflare) or `none`. The loader hides the choice, so site code doesn't change. Local files and SVGs are passed through unchanged (they are already optimised). To use it for every `next/image`, set it once in `next.config.ts`. If the starter already sets an image loader, keep the starter's setting: ```ts // next.config.ts const nextConfig = { images: { loader: 'custom', loaderFile: './src/lib/image-loader.ts' } }; export default nextConfig; // src/lib/image-loader.ts export { default } from '@blanxer-dev/storefront/image-loader'; ``` New or better product photos go **into Blanxer through the MCP** (`blanxer_upload_product_image`, `blanxer_request_image_upload`), so the dashboard, POS, app, feed and site all get them. See [MCP for your website](https://developers.blanxer.com/api-docs/mcp-for-website.md). ## Video and GIFs - No autoplay video backgrounds and no GIF banners by default. A 10-second background video is often heavier than the rest of the page together. - If the merchant insists after hearing the cost, use a short, muted MP4/WebM with a `poster` image, `preload="none"`, no autoplay on mobile, and keep the poster as the LCP image. - An animated banner is better as an AVIF/WebP sequence or CSS animation than a GIF. ## Fonts - Load fonts with `next/font` (`next/font/google` or `next/font/local`). It self-hosts them and avoids layout shift. - At most **2 families**. The store's font (`customization.font`, default Poppins) is usually one of them. - Load only the weights you use, with `display: 'swap'`. - If the site shows Nepali text, pick a family with a `devanagari` subset (for example Mukta or Noto Sans Devanagari) and include that subset. It still counts toward the 2. ## Other speed rules - Read store and catalog data in **server components** (`@blanxer-dev/storefront/server`), not with client-side fetches above the fold. - Keep client components small: cart, variant picker, checkout. Don't make whole pages client components. - Load third-party tags (GA, GTM, Pixel, Clarity, chat widgets) with `next/script` `strategy="afterInteractive"` or `lazyOnload`. - Avoid heavy UI and animation libraries for things CSS can do. They also count toward the Worker size limit (see [Deploy](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#worker-size)). - Don't render page-builder data or embed the Blanxer-hosted site. ## When the check fails | Failure | Fix | |---|---| | A file in `public/` is over 300 KB | Re-run `blanxer-storefront images` with the slot's export width; lower quality to ~65 for photos | | A file is wider than 2560 px | It was committed unresized. Resize it. | | JPEG/PNG found | Convert to AVIF + WebP | | Image without width/height or `sizes` | Add them, or use `fill` + `sizes` | | No image marked as main (warning) / the wrong one | Put `preload` on the LCP image only | | LCP over 2.5 s | Usually the hero: check its size, `preload`, and that nothing (a font, a client fetch, a carousel script) delays it | | Lighthouse under 90 | Read the report's top items; most often images, unused JavaScript or a third-party script loaded too early | ---  # The @blanxer-dev/storefront package > This page summarises the package's API: entry points, functions, components and the CLI. The package README and its TypeScript types have every argument and return type. The package is at version 0.1.0 and not yet published to npm. `@blanxer-dev/storefront` is the typed client, checkout and tooling every BlanxerAPI site uses. The starter already depends on it. Keep it (rule 2): the checkout, delivery, coupon, payment and tracking behaviour in it is copied from Blanxer's own storefront and covered by tests, and it is updated when Blanxer's checkout changes. ```bash npm install @blanxer-dev/storefront ``` Peer dependencies: `next` ≥ 16 (App Router), `react` and `react-dom` ≥ 19. Node ≥ 20.9. ESM with TypeScript types. ## Environment | Variable | Required | Default | Meaning | |---|---|---|---| | `BLANXER_STORE` | Yes | — | The store's subdomain (`mystore` in `mystore.blanxer.io`) or its custom domain, resolved with `check_domain` | | `BLANXER_API` | No | `https://api.blanxer.com` | `https://api-dev.blanxer.com` for sandbox testing | | `SITE_URL` | No | The saved `storefront_url` | The site's public origin, for canonical links, `robots.txt` and the sitemap index | | `NEXT_PUBLIC_BLANXER_IMAGE_LOADER` | No | `wsrv` | Product photo resizing: `wsrv`, `cloudflare` or `none` | No key, token or secret is ever needed (rule 6). ## Entry points | Import | Runs on | For | |---|---|---| | `@blanxer-dev/storefront/server` | Server only | Reading store and catalog data | | `@blanxer-dev/storefront/client` | Browser only | Orders, coupons, payments, holds, tracking, forms, events | | `@blanxer-dev/storefront/react` | Browser (client components) | Provider, cart, product, checkout, the three required pages, forms | | `@blanxer-dev/storefront/seo` | Server | Metadata and JSON-LD | | `@blanxer-dev/storefront/next` | Server | Route handlers and the image loader | | `@blanxer-dev/storefront/core` | Both | The pure logic: delivery, COD rule, coupons, payment method list, order payload, custom fields, validation, variants, formatting, types | | `@blanxer-dev/storefront/image-loader` | — | The default image loader as a default export, for `loaderFile` | | `@blanxer-dev/storefront/styles.css` | — | Default styles for the `bx-*` classes (optional) | | `blanxer-storefront` (CLI) | Your terminal | `check` and `images` | ## `@blanxer-dev/storefront/server` Server-only data functions. Each uses `fetch` with `next: { revalidate: 60 }` and a normal browser `User-Agent`. Responses are also kept in memory per server process / Worker instance for the same 60 seconds, so a Worker without an incremental cache still reads the catalog about once a minute, not once per page view. `opts` is `{ revalidate?: number | false }`. | Function | Returns | |---|---| | `getStore(opts?)` | The full store config from `check_domain`. Server only: it contains plugin data | | `getClientStore(opts?)` / `toClientStore(store)` | The browser-safe subset (no gateway keys or third-party plugin tokens), for `<BlanxerProvider store>` | | `getStoreId()` | The store's `_id` | | `getProducts(opts?)` | Every active product, unpaginated (prefer `getProductsPage`) | | `getProductsPage({ page, perPage, sortBy, sortOrder }, opts?)` | `{ meta, products }`; `perPage` ≤ 100 | | `getProduct(slug)` | The product, or `null` when it is missing, not Active or POS-only | | `getCategory(slug)` | `{ category, storeCategory, products }` or `null`; `new-arrivals` included | | `getBrands()` / `getBrand(slug)` | The brands / `{ brand, page, products }` or `null` | | `searchProducts(q)` | Products (`[]` under 3 characters) | | `getSaleProducts()` | Products on sale | | `getDeliveryCharges()` | `{ defaults, places }` | | `getFlashSales(opts?)` | `{ server_time, sales }` (not cached by default) | | `getBlogPosts({ cursor, category, tag, author, q })` / `getBlogPost(slug)` | `{ items, next_cursor, has_more, all_categories }` / the post or `null` | | `getForm(slug)` | The form or `null` | | `getHomeSeo()` | `{ seo_title, seo_description, seo_image }` from the store's landing page (empty on stores without one) | | `siteOrigin({ fromRequest? })` | The site's public origin: `SITE_URL`, else the saved `storefront_url`, else the request host. `{ fromRequest: false }` returns `''` instead of reading the request, which keeps a page static | | `apiBase()`, `storeHandle()`, `blanxerGet(path, opts?)` | Low-level helpers | Pass `getClientStore()` (or `toClientStore(store)`), not the raw `getStore()` result, to client components. ```tsx // app/product/[slug]/page.tsx import { notFound } from 'next/navigation'; import { getProduct } from '@blanxer-dev/storefront/server'; export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) { const { slug } = await params; const product = await getProduct(slug); // null for missing, non-Active and POS-only products if (!product) notFound(); return <h1>{product.name}</h1>; } ``` See [Catalog](https://developers.blanxer.com/api-docs/catalog.md) for what the product endpoints return. ## `@blanxer-dev/storefront/client` Browser calls. This entry point imports `client-only`, so importing it from a Server Component, route handler or server action fails the build (rule 5). | Function | Calls | |---|---| | `placeOrder(storeId, payload)` | `POST /order/:store_id` | | `applyCoupon({ store, code, products })` | `POST /public/coupon` | | `startPayment(method, { store, order, url? })` | The method's `/payment/*/init`. Returns the next step: `none`, `redirect`, `form`, `qr` or `fonepay_checkout` | | `followPayment(start)` | Performs that step: navigates, or posts the eSewa/NPX form | | `checkPayment('qr' \| 'fonepay_checkout', transaction)` | `GET /payment/dynamic_qr/check/:transaction` or `/payment/fonepay_checkout/check/:transaction` → `boolean` | | `releaseHold({ store_id, order_id, transaction_id })` | `POST /order/public/release-hold` | | `getOrder(storeId, orderId)` | `GET /order/public/:store_id/id/:order_id` | | `cancelOrder({ store_id, order_id, phone_number })` | `POST /order/public/cancel` | | `submitReview({ store_id, product_id, order_id, rating, review, phone_number })` | `POST /order/public/submit-review` | | `requestStockAlert({ store, product, variant_id?, phone?, email?, product_name?, product_url? })` | `POST /customer/stock-alert` | | `submitForm(storeId, slug, data)` | `POST /public/form/:store_id/:slug/submit` | | `trackEvent(event, customData?, { eventId?, email?, phone? })` | Meta Pixel + `POST /public/meta-event/:store_id`, with one event id | Also: `getDeliveryCharges`, `getFlashSaleForProduct`, `notifyFlashSale`, `uploadCustomFieldImage`, `pingAnalytics`, `pixelTrack`, `getEventId`, `buildOrderMeta`, `initMetaCapi`, `configureClient`, `BlanxerApiError`, `errorMessage`, `fieldError`. `url` on orders and payments is always the site's own origin (`window.location.origin`). You rarely call these yourself: the React components do. ## `@blanxer-dev/storefront/react` Client components and hooks. **Unstyled by default**: each element has a `bx-*` class, and the styles read CSS variables. The behaviour is fixed; style it, don't fork it. | Export | What it is | |---|---| | `<BlanxerProvider store apiBase? theme? notify?>` | Wrap the app. Gives components the store config, holds the cart, remembers `?promo=`, sends the session ping, switches the Meta CAPI relay, sets the theme variables, shows toasts | | `useBlanxer()` / `useStore()` | `{ store, storeId, apiBase, notify }` / the store | | `CartProvider`, `useCart()` | The cart in `localStorage['cart_items']`, with line selection (`cart_selection`) | | `<CartLines>`, `<CartView>` | Cart lines (optionally selectable and editable) and a full cart page | | `<AddToCart product>` | Builds the cart line (variant `_id`, weight, custom fields, customization charge). Options to show the price, variants, custom fields, quantity, flash sale and stock alert | | `useProductSelection(product)`, `<VariantPicker>`, `<CustomFields>`, `<QuantityPicker>` | Build your own product form from the same selection state | | `<FlashSaleStrip productId>` | Countdown, units left, per-order limit, notify me | | `<Checkout>` | The whole checkout: form, place select, delivery charge, coupons, payment methods, every gateway, QR modals with the hold timer. See [Checkout](https://developers.blanxer.com/api-docs/checkout.md). | | `<PaymentSuccess>` | `/payment/success` | | `<PaymentFailed method?>` | `/payment/failed` | | `<OrderTracking orderId fromCheckout?>` | `/track/[id]`, with cancel and review | | `<BlanxerForm form>` | A Blanxer custom form (from `getForm()`) | | `<StockAlertForm product variantId?>` | Back-in-stock "Notify me" (alias `BackInStockForm`) | | `<Pixel>` | Meta Pixel, GA4, GTM and Clarity from the store's plugins | | `<Money amount>`, `useMoney()`, `<BlanxerImage>` | Prices with the store's currency label; `next/image` with the Blanxer loader | ### Theming `BlanxerProvider` takes a `theme` prop. Each key sets a CSS variable that the `bx-*` styles read. `primary` defaults to the store's theme colour from Blanxer; the `theme` prop wins over it. | `theme` key | CSS variable | |---|---| | `primary` | `--bx-primary` | | `primaryContrast` | `--bx-primary-contrast` | | `background` | `--bx-bg` | | `foreground` | `--bx-fg` | | `muted` | `--bx-muted` | | `border` | `--bx-border` | | `danger` | `--bx-danger` | | `success` | `--bx-success` | | `radius` | `--bx-radius` | | `fontFamily` | `--bx-font` | Two more variables have no `theme` key: `--bx-surface` (card and panel background) and `--bx-gap` (spacing). Set any of them in your own CSS, or target the `bx-*` classes directly. ```tsx // app/layout.tsx import { getClientStore, apiBase } from '@blanxer-dev/storefront/server'; import { BlanxerProvider, Pixel } from '@blanxer-dev/storefront/react'; import '@blanxer-dev/storefront/styles.css'; export default async function RootLayout({ children }: { children: React.ReactNode }) { const store = await getClientStore(); return ( <html lang="en"> <body> <BlanxerProvider store={store} apiBase={apiBase()} theme={{ primary: '#0f766e', radius: '10px' }}> {children} <Pixel /> </BlanxerProvider> </body> </html> ); } ``` ```tsx // app/checkout/page.tsx import { getDeliveryCharges } from '@blanxer-dev/storefront/server'; import { Checkout } from '@blanxer-dev/storefront/react'; import { noIndexMetadata } from '@blanxer-dev/storefront/seo'; export const metadata = noIndexMetadata('Checkout'); export default async function CheckoutPage() { const delivery = await getDeliveryCharges(); return <Checkout delivery={delivery} />; } ``` `Checkout` also takes `labels` (button and section text), `className`, `header` and `footer` (your own content above the form and under the place-order area), `paymentMethodIcons` and `onOrderPlaced(order, method)`. Without `delivery`, it fetches the delivery table in the browser. ```tsx // app/payment/success/page.tsx (likewise PaymentFailed and OrderTracking) import { PaymentSuccess } from '@blanxer-dev/storefront/react'; import { noIndexMetadata } from '@blanxer-dev/storefront/seo'; export const metadata = noIndexMetadata('Payment'); export default function Page() { return <PaymentSuccess />; } ``` ### "Checkout Powered by Blanxer" `Checkout` always renders this under the place-order button: ```html <p class="bx-powered-by">Checkout Powered by <a href="https://blanxer.com" target="_blank" rel="noopener noreferrer">Blanxer</a></p> ``` - Restyle it through `.bx-powered-by` (and `.bx-powered-by a`): colour, size, font, alignment, spacing. - **Never remove or hide it** (rule 2). There is no prop to turn it off. Don't hide it with CSS (`display: none`, `visibility: hidden`, zero size, off-screen, same colour as the background) and don't cover it. - Your own `footer` content renders below it. ### Where the package differs from the hosted storefront - Test contacts (phone `0000000000` or a `mailinator.net` email) get `{ success: true }` with no order. The hosted storefront then goes to `/track/undefined`; `Checkout` shows "Test order accepted" and keeps the cart. - Not ported on purpose: the customer login gate, loyalty tier discount and points preview (custom sites have no login), store-specific variants, and Card (Cybersource), which stays off. - `Checkout` offers the optional delivery date from today only, like storefront `main`; the newer backend delivery-date rules aren't on `main` either. - Payment methods are shown by name; logos are opt-in through `paymentMethodIcons`. - The package re-selects a payment method that disappears, re-checks the coupon when the cart total changes, and shows per-method payment-start errors. See [Checkout](https://developers.blanxer.com/api-docs/checkout.md). ## `@blanxer-dev/storefront/seo` | Export | Returns | |---|---| | `storeMetadata(store, { origin?, homeSeo? })` | Home `Metadata` (pass `homeSeo` from `getHomeSeo()`) | | `productMetadata(product, store, { origin? })` | Product `Metadata` | | `categoryMetadata(store, category, { origin? })` | Category `Metadata` | | `brandMetadata(store, brand, page?, { origin? })` | Brand `Metadata` | | `blogPostMetadata(post, store, { origin? })` | Blog post `Metadata` | | `noIndexMetadata(title)` | `noindex` metadata for cart, checkout, payment and tracking pages | | `verificationMetadata(store)` | Search Console and other `meta_tags` from the store's plugins | | `productJsonLd`, `organizationJsonLd`, `breadcrumbJsonLd` | schema.org `Product`, `Organization`, `BreadcrumbList` | | `jsonLd(data)` | A safe serialiser for `<script type="application/ld+json">` | Canonical URLs are only emitted when the origin is known. What they produce: [SEO and tracking](https://developers.blanxer.com/api-docs/seo-and-tracking.md). ### Site tags (0.1.1+) `storeMetadata` adds two tags to every page: `<meta name="generator" content="Blanxer Storefront">` and `<meta name="blanxer-store" content="<store id>">`. - **What they're for:** Blanxer's nightly check reads them to confirm that the website link saved for a store is that store's own site. A site that answers but lacks them stays "linked", not "live", in Blanxer's records. - **Keep them:** keep `storeMetadata` in the root layout. ## `@blanxer-dev/storefront/next` | Export | Use | |---|---| | `sitemapIndexRoute({ extra? })` | `export const GET = sitemapIndexRoute()` in `app/sitemap.xml/route.ts`: an index of `/sitemap-catalog.xml` plus your own extra sitemaps | | `catalogSitemapRoute()` | `export const GET = catalogSitemapRoute()` in `app/sitemap-catalog.xml/route.ts`. Proxies `/public/sitemap/:store_id.xml`. | | `robotsRoute({ disallow? })` | `export const GET = robotsRoute()` in `app/robots.txt/route.ts` | | `blanxerImageLoader`, `createImageLoader(provider)` | `next/image` loader for product photos (asks a resize service for the width needed) | ## CLI ```bash npx blanxer-storefront check [dir] [--lighthouse <origin>] [--offline] [--no-worker-size] [--json] npx blanxer-storefront images <in> <out> [--max-width 2560] [--quality 75] [--formats avif,webp] ``` ### `check` Run before every deploy. It prints a PASS/FAIL table and fails when: - `BLANXER_STORE` isn't set, or Next.js or the package is missing; - a contract route is missing: `/`, `/products`, `/product/[slug]`, `/collections/[slug]`, `/brand/[slug]`, `/brands`, `/search`, `/sale`, `/cart`, `/checkout`, `/payment/success`, `/payment/failed`, `/track/[id]`, `/forms/[slug]`, `/blogs`, `/blog/[slug]`, `/sitemap.xml`, `/sitemap-catalog.xml`, `/robots.txt`; or `/checkout` doesn't render the package's `<Checkout>`; - there are account, login, wishlist, rewards or `/p/` pages, or calls to `/customer/auth`, `/customer/account`, wishlist or rewards; - a secret is in the code, env files, `wrangler` config or the build output (`sk_` keys, gateway keys, plugin tokens, passwords, JWTs); - `@blanxer-dev/storefront/client` is imported by server files, or the code calls payment, coupon or hold endpoints directly; - the image budget is broken: see [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md#size-per-slot). It also warns when no image on a page is marked as the main (LCP) image; - with `--lighthouse <origin>` (the production build running with `next start`): Lighthouse mobile is under 90 or LCP over 2.5 s on the home page, one product page and `/checkout`. It runs `npx --yes lighthouse` and needs Chrome. It also lists the store's delivery places and payment methods. `--offline` skips the network checks. After an OpenNext build it reports the Worker size against the 3 MiB free-plan limit. ### `images` Resizes images (never enlarges; default max width 2560, `--max-width` to change it), writes AVIF and WebP (~75 quality; `--quality`, `--formats`), copies SVGs, strips EXIF and location data, and prints a before/after size report. Needs `sharp` (an optional dependency of the package). See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md#optimising-a-merchants-images). ## Versions The checkout is versioned: checkout v1 matches Blanxer's storefront `main` at `cabd695` (stock holds and flash sales included). Partial payment, offers and agreed delivery come in checkout v1.1. Update the package to get checkout fixes; the site code doesn't change. ---  # MCP for your website The site's code only **reads** Blanxer, through the public API. Everything you **change** in the store while building (SEO text, products, photos, categories, coupons, delivery charges, the site link) you change through the Blanxer MCP, in your chat with the merchant. The site never holds a key and never calls the MCP (rule 6). ## Connect The server is `https://mcp.blanxer.com/mcp` (streamable HTTP). The merchant signs in to Blanxer in the browser (OAuth). You never see a password or key, and you never ask for one. **Claude Code** ```bash claude mcp add --transport http blanxer https://mcp.blanxer.com/mcp ``` Or install the skill, which brings the MCP with it: ``` /plugin marketplace add blanxer-dev/blanxer-agent-skills /plugin install blanxer-website@blanxer ``` Then run `/mcp`, pick `blanxer` and sign in. **Cursor**: add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json`: ```json { "mcpServers": { "blanxer": { "url": "https://mcp.blanxer.com/mcp" } } } ``` **Codex**: add to `~/.codex/config.toml`: ```toml [mcp_servers.blanxer] url = "https://mcp.blanxer.com/mcp" ``` Sign in when Codex asks (recent versions: `codex mcp login blanxer`). **claude.ai**: Settings → Connectors → Add custom connector → URL `https://mcp.blanxer.com/mcp`. The tools act as the person who signed in, with their role in the store. Most writes need the **owner** or a **manager**. If a tool says the role isn't allowed, ask the merchant to sign in as the owner. ## What you use it for | While building the site you… | MCP tool | The site reads it from | |---|---|---| | Find SEO gaps | `blanxer_audit_seo` | — | | Write product titles and descriptions for search | `blanxer_update_product_status_seo`, `blanxer_bulk_update_products` | Product `seo_*` → page metadata | | Write category and brand SEO | `blanxer_bulk_update_categories_seo`, `blanxer_update_category`, `blanxer_update_brand` (brand SEO is saved only when the brand has a page; `''` can't clear a field) | `check_domain.categories`, brand details | | Verify Search Console, add GA / GTM | `blanxer_set_site_verification` | `check_domain.plugins` → the package renders the tags | | Add products and photos | `blanxer_create_product`, `blanxer_bulk_create_products`, `blanxer_bulk_import_products`, `blanxer_upload_product_image`, `blanxer_request_image_upload` | Product endpoints | | Create categories and brands for the menus | `blanxer_create_category`, `blanxer_create_brand`, `blanxer_reorder_categories` | Categories / brands | | Set up launch coupons | `blanxer_create_coupon` | `/public/coupon` | | Fix delivery places, charges and COD | `blanxer_get_delivery_charges`, `blanxer_update_delivery_charges` | `/public/delivery_charge` | | Change the store name or description (shared with the Blanxer site) | `blanxer_update_store_profile` (only the top-level `name` and `description`) | `check_domain.name`, `description` | | Change logo, favicon, brand name or colours (shared with the Blanxer site and emails) | `blanxer_update_appearance` | `check_domain.customization` | | Write blog posts | `blanxer_create_blog_post` (an empty post), then its body with `blanxer_add_section` / `blanxer_update_section` using `{ post_id }`, then `blanxer_set_blog_post_status` | `/public/blog/*` | | **Save the website link** | **`blanxer_set_storefront_url`** (new): preview, then `{ dry_run: false, confirm_token }` | — | | Get the feed and sitemap URLs | `blanxer_get_store_context` (only once a website link is saved) | — | | Retire the subdomain site | `blanxer_update_appearance { store_visibility: 'hidden_on_subdomain' }` | — | `blanxer_how_to` returns step-by-step guides for store tasks (SEO pass, editing products, and more). For the whole custom-site flow: `blanxer_how_to { operation: 'custom_website' }`. With a website link saved, `blanxer_audit_seo` treats the custom site as the live site and reports `<site>/sitemap.xml` as the sitemap to submit. ### `blanxer_set_storefront_url` ``` blanxer_set_storefront_url { url: "https://mystore.com" } // preview a save or change blanxer_set_storefront_url { url: null } // preview clearing it blanxer_set_storefront_url { dry_run: false, confirm_token: "..." } // apply, after the merchant's yes ``` - Owner or manager. - **The first call saves nothing.** It shows the old and the new value and returns a `confirm_token`. Show the merchant the change; after their yes, call again with `{ dry_run: false, confirm_token }` only. If the link changed since the preview, the apply is refused; preview again. - Blanxer cleans the link to `https://<host>`: it must be `https`, with no path, query, port or login, and not an IP or `localhost`. A bare `mystore.com` becomes `https://mystore.com`. A `*.workers.dev` link is fine. The MCP refuses `*.blanxer.io` and `*.blanxer.com` addresses (those are the Blanxer-hosted site). - A save returns the product feed URL, the sitemap URL, and a reminder about the subdomain switch. Clearing returns only a confirmation (and a warning if the subdomain site is still hidden). Once saved, Blanxer uses the site in: - the tracking link it generates (dashboard copy, `get_tracking_link`); - the confirmation emails of orders created in the dashboard, as leads or through Sambad (orders placed on the site use the site's own `url`); - the delivered email; - flash-sale alerts: the alert links to the `url` the site sent with "Notify me", which is kept only when it is on the store's domains, the saved link included; - the product feed and the catalog sitemap. Whether SMS short links follow it is not yet verified. Clearing the link puts these back on the custom domain if the store has one, else the subdomain (the delivered email falls back to `<sub>.blanxer.com`). This tool ships with the BlanxerAPI release of the Blanxer MCP. Until your MCP lists it, the merchant pastes the link in the Blanxer dashboard → avatar menu → BlanxerAPI → Your website (rolling out). ## Confirm before bulk changes (rule 13) Store data is live and shared with the dashboard, POS and mobile app. Before any change that touches many records (SEO for many products, imports, category renames, delivery charges): 1. Run the tool with `dry_run: true` where it has one, or list what will change. 2. Show the merchant the list or a sample, with counts. 3. Apply only after a clear yes. The MCP's own confirmations still apply on top of this. Never invent product facts, reviews or claims in SEO text; use the product's own data and the merchant's words. ## What not to do - **Don't use the page-builder tools on a custom site** (rule 12). These change the **Blanxer-hosted** site only: - `blanxer_add_section`, `blanxer_update_section`, `blanxer_move_section`, `blanxer_remove_section`, `blanxer_duplicate_section` - `blanxer_apply_page_template`, `blanxer_create_page`, `blanxer_update_page`, `blanxer_duplicate_page`, `blanxer_delete_page` - `blanxer_update_navigation`, `blanxer_update_footer` The custom site's design, menus and footer live in its code. **Exception: blog post bodies.** `blanxer_create_blog_post` makes an empty post; write its body with `blanxer_add_section` / `blanxer_update_section` using `{ post_id }`. That is content the site shows (the post's `sections`), so use them for blog posts. - Don't use the MCP from the site's code, and don't put an MCP token anywhere. - Don't change `store_visibility` unless the merchant asks (see [Deploy → Retiring the old subdomain site](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#retiring-the-old-subdomain-site)). - Don't put product photos in the site's repo; upload them to Blanxer. ---  # Testing Test the site before it goes live, and once more after. There are three tools: the `0000000000` test order (any store), the sandbox store on `api-dev`, and the live check. ## 1. Run the check command ```bash npx blanxer-storefront check ``` Fix every failure first. What it checks: [Package → check](https://developers.blanxer.com/api-docs/package.md#check). ## 2. Test orders that create nothing On **any** store, including the merchant's real one, an order with: - `customer_phone_number` = `0000000000`, or - a `customer_email` containing `mailinator.net` returns HTTP 200 `{"success": true}` and **creates no order**: no stock change, no SMS, no email, nothing in the dashboard. - The body is validated **before** this check, so every other field must be valid. Use it to test validation messages too: leave the name empty and you get the real error. - The response has no `_id`. The package's checkout stops there and shows "Test order accepted — no order was created for this test phone/email.": no payment start, no redirect, nothing in `sessionStorage`. - It can't test payments, stock holds or the tracking page, because no order exists. - Test orders still count toward the limit of 5 orders per 10 minutes per store and IP. After 5, wait or you get HTTP 429. - Applying a coupon is real even here: for a coupon with a usage limit, each successful apply holds one use for about 12 seconds. Don't test a coupon with very few uses left. Use it for the form, the place select, delivery charges, COD availability per place, coupons (apply, then place), and that the request leaves from the browser (rule 5). ## 3. The sandbox store A sandbox store on `https://api-dev.blanxer.com` is planned for BlanxerAPI: every gateway in test mode, products with variants, weights and custom fields, delivery places with and without COD, coupons and a live flash sale. Its subdomain will be listed here when it is ready. **Until then, check the gateway and QR screens live** (see [the live check](#4-the-live-check)): the `0000000000` order creates nothing, so it never opens them. Point the site at it: ```bash BLANXER_API=https://api-dev.blanxer.com BLANXER_STORE=<sandbox subdomain> ./node_modules/.bin/next dev ``` On the sandbox, place: | Order | Expect | |---|---| | One COD order | Lands on `/track/<id>?from=checkout` with the congratulations banner | | One order per gateway the **real** store has on | Returns to `/payment/success`, then `/track/<id>` | | One cancelled payment (cancel on the gateway page) | Returns to `/payment/failed` | | One QR order left to expire | The timer runs out, "QR is expired" shows, and the hold is released (the units are buyable again) | | One QR order closed with ✕ → "Yes, cancel payment" | The hold is released at once | Notes: - Run the gateway tests on a deployed preview, or locally on `http://127.0.0.1:3000`. eSewa, Khalti and FonePay reject `http://localhost` as the return `url` (HTTP 400 `Valid Return URL is required`). - On `api-dev`, Checkout by Fonepay uses Fonepay's development credentials and asks for 1.1, not the order total. - An eSewa store in test mode has `product_code` `EPAYTEST` and posts to `rc-epay.esewa.com.np`. - The `api-dev` database is shared with Blanxer's own development. Only create orders on the sandbox store. ## 4. The live check After deploying and saving the link in Blanxer: 1. Open, on the live site: home, a product, a category, `/checkout`, `/payment/success`, `/payment/failed`, and a real `/track/<id>` (the merchant can give you one from the dashboard). 2. With the merchant's OK, place **one real COD order** on the real store with the merchant's own phone number. Check it reaches `/track/<id>`, appears in the dashboard, and the confirmation email links to the new site. 3. Have the merchant **cancel it in the dashboard**, so stock goes back and it doesn't count as a sale. 4. For one online method the store uses, place a real order and open the gateway or QR screen, then stop without paying. Close the QR screen with ✕ → "Yes, cancel payment" (that releases the stock hold). Have the merchant cancel the order in the dashboard. 5. Run Lighthouse (mobile) on home, a product and checkout: ≥ 90, LCP < 2.5 s. 6. Check `/sitemap.xml`, `/sitemap-catalog.xml` (its links must be on the live domain) and `/robots.txt`. Don't make real online payments yourself. If the merchant wants to confirm a gateway, they pay a small real order themselves and refund or cancel it in Blanxer. ---  # Deploy to Cloudflare The site runs on Cloudflare Workers in the **merchant's own Cloudflare account**. Blanxer doesn't host it and never gets access to that account. ## The toolchain - Next.js 16, App Router, TypeScript. - [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), which runs the real `next build` and turns the output into a Worker. - `wrangler`, Cloudflare's CLI. The starter already has `wrangler.jsonc`, `open-next.config.ts` and these scripts: | Script | Runs | |---|---| | `dev` | `next dev` (local, Node) | | `build` | `next build` | | `preview` | `opennextjs-cloudflare build && opennextjs-cloudflare preview`: the real Worker, locally | | `deploy` | `opennextjs-cloudflare build && opennextjs-cloudflare deploy` | This page calls the binaries directly (`./node_modules/.bin/opennextjs-cloudflare ...`); the scripts do the same. Deploy to **Workers**, not Cloudflare Pages. Don't swap the adapter: Blanxer tests the checkout against this setup. ## Configuration The site reads its settings from `.env`. OpenNext copies `.env` into the Worker at build time, so the same file works locally and deployed. None of these is a secret. | Variable | Required | Meaning | |---|---|---| | `BLANXER_STORE` | Yes (`check` fails without it) | The store's subdomain, e.g. `mystore` | | `BLANXER_API` | No | API base, default `https://api.blanxer.com` (`https://api-dev.blanxer.com` for sandbox testing) | | `SITE_URL` | No | The site's public origin, for canonical links, `robots.txt` and the sitemap index. Default: the website link saved in Blanxer (`storefront_url`) | | `NEXT_PUBLIC_BLANXER_IMAGE_LOADER` | No | Product photo resizing: `wsrv` (default), `cloudflare` or `none` | **Before the first deploy, rename the Worker** in `wrangler.jsonc`: set `name` to the merchant's site name, and the `WORKER_SELF_REFERENCE` service binding's `service` to the same value. The name is part of the `workers.dev` link. ```jsonc { "name": "mystore", "services": [{ "binding": "WORKER_SELF_REFERENCE", "service": "mystore" }] } ``` Keep the rest of the starter's `wrangler.jsonc` as it is. No other configuration is needed: the public API needs no key, and nothing secret belongs in the Worker (rule 6). ### Caching on the Worker The starter has no R2 or KV cache configured, so a new merchant can deploy without creating Cloudflare resources. Pages render on each request, and the package keeps API reads in memory for 60 seconds per Worker instance. For full ISR, create an R2 bucket and turn on the R2 incremental cache: the steps are commented in the starter's `open-next.config.ts` and `wrangler.jsonc`. ## Sign in to Cloudflare ```bash npx wrangler login npx wrangler whoami ``` - **Normal case:** a browser opens. The merchant signs in to **their own** Cloudflare account (a free account is enough) and approves access. You never see their password. `whoami` shows which account you are on; confirm it with the merchant. - **No browser** (remote machine, CI): the merchant creates an API token in Cloudflare → My Profile → API Tokens → Create Token → template **Edit Cloudflare Workers**, and sets it in **their own** terminal: ```bash export CLOUDFLARE_API_TOKEN=... # and CLOUDFLARE_ACCOUNT_ID=... if they have several accounts ``` Don't ask them to paste the token into the chat, and never write it to a file in the repo. ## Worker size ```bash ./node_modules/.bin/opennextjs-cloudflare build ``` The build prints the Worker's size. The **compressed** size must be under: - **3 MiB** on the Workers **free** plan; - **10 MiB** on the Workers **paid** plan ($5/month). Static assets (images, CSS, client JavaScript chunks) don't count toward it. If the Worker is over 3 MiB, tell the merchant **before** deploying and offer: - remove heavy server-side dependencies (large UI kits, date and icon libraries imported whole, markdown or PDF libraries on the server); - move work out of server code where it isn't needed; - or the $5/month paid plan. ## Preview, then deploy ```bash ./node_modules/.bin/opennextjs-cloudflare build && ./node_modules/.bin/opennextjs-cloudflare preview # the real Worker, locally ./node_modules/.bin/opennextjs-cloudflare build && ./node_modules/.bin/opennextjs-cloudflare deploy ``` The deploy ends with the live link: `https://<worker-name>.<account-subdomain>.workers.dev`. Then check, on that link: - the home page, a product, a category and `/checkout` load with real data; - `/payment/success`, `/payment/failed` and `/track/<a real order id>` exist (not 404); - `/sitemap.xml`, `/sitemap-catalog.xml` and `/robots.txt` respond. ## Link the site to Blanxer 1. Save the link: `blanxer_set_storefront_url { url: "https://<the workers.dev link or the custom domain>" }` through the MCP. That call is a preview with a `confirm_token`; after the merchant's yes, apply it with `{ dry_run: false, confirm_token }`. Or the merchant pastes it in the Blanxer dashboard → avatar menu → BlanxerAPI → Your website (rolling out). Blanxer then uses it for the tracking link it generates, the delivered email, flash-sale alerts, the product feed and the sitemap. See [MCP for your website](https://developers.blanxer.com/api-docs/mcp-for-website.md#blanxersetstorefronturl) for the full list. 2. Register the product feed `https://api.blanxer.com/public/product-feed/<store_id>.xml` with Meta Commerce Manager and/or Google Merchant Center. 3. Verify the site in Google Search Console and submit `https://<site>/sitemap.xml`. Details for 2 and 3: [SEO and tracking](https://developers.blanxer.com/api-docs/seo-and-tracking.md). ## Custom domain (optional) 1. The domain must be a zone on the merchant's Cloudflare account. In Cloudflare: **Add a domain**, then change the nameservers at the registrar if Cloudflare asks. This can take a few hours. 2. **Workers & Pages** → the Worker → **Settings** → **Domains & Routes** → **Add** → **Custom domain** → enter `mystore.com` (and `www.mystore.com` if wanted). Cloudflare creates the DNS record and the certificate. 3. Pick one host as the main one and redirect the other to it (a Cloudflare redirect rule, `www` → apex or the reverse). 4. Update the Blanxer link (step 1 above) to `https://mystore.com`. **If the domain currently points at Blanxer** (it appears as `custom_domain` in `check_domain`), moving it to the Worker switches every shopper on that domain from the Blanxer-hosted site to the new site, at once. Explain that, and let the merchant decide when. ## Retiring the old subdomain site Optional, the merchant's choice, and **only after the link is saved**. - Through the MCP: `blanxer_update_appearance { store_visibility: 'hidden_on_subdomain' }`; - or in Blanxer: **Appearance → Branding → Site under construction → Sub-domain**. Tell the merchant plainly, before switching: - **every** page on `<sub>.blanxer.io` shows a placeholder, **including tracking and payment links sent before today**. There is no exception for old `/track` or `/payment` links; - new orders' links go to the new site; - it can be switched back at any time (`store_visibility: 'live'`). The switch only affects the Blanxer-hosted pages. The API, and so the custom site, keeps working: `check_domain?domain=<sub>` still answers. ## Redeploying later 1. Edit the code. 2. `./node_modules/.bin/next build` and `npx blanxer-storefront check`. 3. `./node_modules/.bin/opennextjs-cloudflare build && ./node_modules/.bin/opennextjs-cloudflare deploy`. Store data changes (products, prices, stock, SEO text, delivery charges, coupons) need **no** redeploy. They show on the site within about a minute. ## Hand-over Leave a `README.md` in the site repo for the merchant (or their developer): how to run it locally, how to change the design, how to redeploy (`opennextjs-cloudflare build && opennextjs-cloudflare deploy`), which Cloudflare account it lives on, which domain, and that products and SEO are edited in Blanxer, not in the code. ---  # Troubleshooting Find the symptom, then the fix. API errors come back as HTTP 400 `{"message": "..."}` unless noted; validation errors as `{"error_type": "zod_validation", "fields": {...}}` or `{"fields": {...}}`. ## Checkout and payments ### The shopper gets a 404 after paying The gateway returned to `<url>/payment/success` or `<url>/payment/failed`, and that page doesn't exist on the site. - Add `/payment/success`, `/payment/failed` and `/track/[id]` at exactly these paths, with the package's `PaymentSuccess`, `PaymentFailed` and `OrderTracking` (rule 3). - `url` must be the site's origin with no path and no trailing slash: `window.location.origin`. Blanxer appends `/payment/success` to it as is. - Never hardcode `url` (rule 4). A hardcoded `workers.dev` origin sends shoppers back to the old host after the custom domain is added. ### `/payment/success` sends the shopper to the home page instead of their order The success page reads the order id from `sessionStorage['checkout_order_id']`, which only exists on the origin where the checkout ran. - Serve the site on **one** host. Redirect `www` to the apex (or the reverse) so checkout and success are on the same origin. - Don't clear `sessionStorage` in your own code. - A shopper who finished paying on another device or browser has no session there; they land on `/`. Their order is fine and the confirmation email links to `/track/<id>`. ### `Selected delivery city not found, please try again` The order's `customer_address_city` doesn't exactly match a place name in the store's delivery table. - Fill the place select only from `GET /public/delivery_charge/<store_id>`. Never type place names into the code. - Send the place **name** as `customer_address_city`, not the address. - The merchant may have renamed a place; the site's cached table is at most a minute old. Reload. ### `Cash on delivery is not available for the selected delivery location` The order asked for COD at a place where the store turned COD off. - COD is allowed only when the place's flag is `true` or `'Y'`. A check like `!!cod` treats `'N'` as yes: that is a known bug in the Blanxer-hosted storefront; the package doesn't copy it. - When the shopper changes the place and COD disappears from the list, the selected method must change too (the first available one). ### The coupon shows a discount, but the order has none The order was sent with the coupon **code** (`"coupon": "DASHAIN10"`). The server only reads `coupon` when it is longer than 20 characters (an id), so a code is ignored **silently**: no discount, no error. - Send the `_id` returned by `POST /public/coupon` (rule 2: use the package's checkout, which does this). - Compare the order response: `total_price` already has the discount taken off. ### Coupon errors | Message | Cause | |---|---| | `Coupan not found` | No coupon with that exact code in this store. Codes are case-sensitive: the input is upper-cased, but a `?promo=` link is sent as written, so `?promo=dashain10` fails for `DASHAIN10` | | `Coupon not found` (at order time) | The coupon `_id` sent with the order no longer exists | | `Coupon is inactive` | Turned off in Blanxer | | `All the available coupons have been used.` | Used up. For a coupon with a usage limit, each successful apply also holds a use for about 12 seconds, so on the last use an order placed right after Apply can fail with this. Wait a few seconds and place it again | | `Coupon code not available` / `Coupon code is expired` | Before its start / after its end | | `Coupon is not applicable to any products` | A category coupon and no line in those categories | | `Coupon is only applicable for order value above N` | Subtotal + customization + delivery under the minimum | | `Only cash on delivery can use this coupon` / `Only online payment method can use this coupon` | Payment method restriction | | `This coupon is not valid for <place>` | Place restriction | ### `Valid Return URL is required` `POST /payment/esewa/init`, `/payment/khalti/init` and `/payment/fonepay/init` reject `http://localhost:3000` as `url`. Test on `http://127.0.0.1:3000`, on the OpenNext preview opened via `127.0.0.1`, or on the deployed site. ### `Variant selection required for this product` / `Either of the selected product has been modified, please add to cart again` - The cart line has no `variant`, or a variant `_id` that no longer exists (the merchant edited the variants). - Make sure `AddToCart` stores the variant **`_id`**, not its name. - For old carts: drop the line and ask the shopper to add it again. ### `Please choose a print for <name>` The product has a required print add-on, and the line has no `print_id`. The package has no print picker yet, so it can't sell that product. Ask the merchant to make the print optional, or leave the product off the site for now. See [Checkout → Print add-on products](https://developers.blanxer.com/api-docs/checkout.md#print-add-on-products). ### `Either of the selected product is already deleted` / `... is out of stock` The product is no longer Active, or the stock is lower than the quantity (and it doesn't continue selling). Refresh the cart from the product data. ### `The last units of an item in your cart are in other shoppers' checkouts right now...` Other shoppers hold the last units while they pay. It clears within the hold time (5 minutes; 2–5 during a flash sale). Show the message as is. ### HTTP 429 when placing orders More than 5 order requests in 10 minutes from one IP for one store. Every request counts, including `0000000000` test orders and failed ones. The body is plain text (`Too many requests, please try again later.`), not JSON; handle that. If **every** shopper hits it, orders are being sent from the server (one shared Worker IP for everyone): move the call to the browser (rule 5). ### The QR payment never confirms - The page checks while the tab is **visible** (every 5 s for Fonepay QR, 10 s for Checkout by Fonepay) and when the shopper returns to it. Ask them to come back to the tab or press "Check payment". - Never close the QR or release the hold on tab switch; shoppers pay in their banking app with the QR open. - `Payment not received` from the check endpoint only means "not yet". ### The eSewa page shows an error from api.blanxer.com after the shopper cancels eSewa sends both success and failure back to the same API endpoint. A return without eSewa's `data` parameter may end on an API error page instead of `/payment/failed`. This is on Blanxer's side and is being verified; the order stays `Inactive`, and the shopper can go back to the site. ### Khalti shows an error before redirecting Khalti's own error text is passed through (for example a minimum amount or a configuration problem). Show it; the merchant may need to fix their Khalti settings in Blanxer. If it reads `[object Object]`, Khalti returned a structured error; check the store's Khalti keys in Blanxer. ## Catalog and data ### A Draft or POS-only product page is visible `GET /product/public/<store_id>/<slug>` also returns non-Active (`Draft`, `Archived`) and POS-only products. The page must call `notFound()` unless `status === 'Active' && channel !== 3`; the package's `getProduct()` returns `null` for them. See [Catalog → One product](https://developers.blanxer.com/api-docs/catalog.md#one-product). ### A product page shows "Product not found" as an error instead of a 404 An unknown slug is HTTP **400** `Product not found`, not 404. Catch it and call `notFound()`. ### Prices or stock lag behind the dashboard The site caches data for 60 seconds. The API caches the product lists for up to 1 hour and clears them when the merchant saves products, categories or settings. Orders don't clear it, so stock in lists can lag by up to an hour; the product page itself isn't cached by the API. The checkout always charges the current server price and checks the current stock. ### `Domain not in use` `BLANXER_STORE` is wrong. It is the subdomain only (`mystore`), not `mystore.blanxer.io` and not the custom-site domain. ### Server-side reads fail with Cloudflare error 1010 Public reads have been checked to work from plain `fetch`, `curl` and Node. The package sends a normal `User-Agent`. If a Worker still gets 1010, report it to Blanxer with the time and URL; don't work around it with a proxy. ## SEO ### The catalog sitemap or product feed links to `<sub>.blanxer.io` The site link isn't saved in Blanxer. Call `blanxer_set_storefront_url` (preview, then `{ dry_run: false, confirm_token }`), or the merchant saves it in BlanxerAPI → Your website. The API uses it on the next request, but HTTP caches (`max-age=3600`, plus `stale-while-revalidate`) and the site's own `/sitemap-catalog.xml` can serve old links for an hour or more. ### Search Console says the verification tag is missing - Check the home page source for `<meta name="google-site-verification" ...>`. The site must render the store's `meta_tags` plugin (`verificationMetadata(store)`). - After `blanxer_set_site_verification`, wait about a minute for the API and site caches. - The property in Search Console must be the exact host the site is served on (`https://mystore.com/`, not `www.` if that redirects). ### The shopper got no confirmation email - With `checkout.receiver_info` on and a sender name filled, the email goes only to `sender_email`; none is sent when that is empty. - Online orders are emailed only once paid. COD orders are emailed when created. ### Confirmation emails link to the wrong site The email uses the `url` sent with **that** order. Orders placed before a domain change keep the old link. Make sure the checkout sends `window.location.origin`. ## Deploy ### The Worker is over 3 MiB The Workers free plan allows 3 MiB compressed. Tell the merchant before deploying, then: - remove heavy server-side dependencies (whole icon sets, UI kits, date libraries, markdown/PDF tools used on the server); - keep large libraries out of server components; - or move to the $5/month Workers paid plan (10 MiB). See [Deploy → Worker size](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#worker-size). ### `wrangler` deploys to the wrong Cloudflare account Run `npx wrangler whoami`. If it's not the merchant's account, `npx wrangler logout`, then `npx wrangler login` and have the merchant sign in. With several accounts, set `CLOUDFLARE_ACCOUNT_ID`. ## Images ### Images too big / the image budget fails Every file in `public/` must be ≤ 300 KB and ≤ 2560 px wide, as AVIF/WebP, rendered with `next/image` and a size. Re-run `npx blanxer-storefront images` with the right export width for the slot (hero 2560, banner 1600, card 800). Never commit originals. Product photos belong in Blanxer, loaded through `blanxerImageLoader`. See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md). ## `npx blanxer-storefront check` failures | Failure | Fix | |---|---| | Missing route `/checkout`, `/payment/success`, `/payment/failed` or `/track/[id]` | Add it at that exact path with the package component | | Secret found | Remove it from code, `.env` and the build. No key is ever needed (rule 6) | | `/customer/auth` or `/customer/account` call, or a login/account/wishlist/rewards page | Remove it (rule 7). Only `/customer/stock-alert` is allowed | | Order or payment call outside the browser | Move it into a client component; no server actions or route handlers for orders, coupons, payments, holds or stock alerts (rule 5) | | Image budget | See above | | No image marked as main (warning) | Add `preload` to each page's main (LCP) image. See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md#loading-images) | | Lighthouse under 90 / LCP over 2.5 s | See [Images and speed → When the check fails](https://developers.blanxer.com/api-docs/images-and-speed.md#when-the-check-fails) |

# BlanxerAPI: all guides in one file > Every page of https://developers.blanxer.com/api-docs, concatenated in sidebar order. Index: https://developers.blanxer.com/llms.txt. API spec: https://developers.blanxer.com/openapi.yaml. --- # BlanxerAPI developer docs Build a custom Next.js website for a Blanxer store and deploy it to the merchant's own Cloudflare account. Blanxer stays the admin: products, stock, orders, payments, delivery and SEO data are managed in Blanxer, and the website is the front end. > **AI agents:** read [llms.txt](https://developers.blanxer.com/llms.txt), then follow the [Quickstart](https://developers.blanxer.com/api-docs/quickstart.md). Everything is also in [one file](https://developers.blanxer.com/llms-full.txt). Merchants start with one line to their AI agent: > Build my Blanxer store website in Next.js and deploy it to my Cloudflare account. Follow https://developers.blanxer.com/llms.txt My store is `.blanxer.io`. ## How it fits together | Channel | Who uses it | What for | |---|---|---| | Public API, `https://api.blanxer.com` | The website | Store, catalog, delivery, coupons, orders, payments, tracking. No key. | | Blanxer MCP, `https://mcp.blanxer.com/mcp` | The agent, while building | Store data: SEO text, products and photos, categories, coupons, the site link. The merchant signs in. | | Blanxer XML files | Google and Meta | Product feed and catalog sitemap | ## Install - Claude Code skill: `/plugin marketplace add blanxer-dev/blanxer-agent-skills` then `/plugin install blanxer-website@blanxer` - Blanxer MCP: `claude mcp add --transport http blanxer https://mcp.blanxer.com/mcp` - The site: start from `blanxer-dev/blanxer-storefront-starter`, which uses the `@blanxer-dev/storefront` package. ## Guides - [Quickstart](https://developers.blanxer.com/api-docs/quickstart.md): the procedure, step by step - [The 13 hard rules](https://developers.blanxer.com/api-docs/rules.md) - [Store and theme](https://developers.blanxer.com/api-docs/store-and-theme.md) · [Catalog](https://developers.blanxer.com/api-docs/catalog.md) · [Checkout](https://developers.blanxer.com/api-docs/checkout.md) · [Forms and extras](https://developers.blanxer.com/api-docs/forms-and-extras.md) - [SEO and tracking](https://developers.blanxer.com/api-docs/seo-and-tracking.md) · [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md) · [Package](https://developers.blanxer.com/api-docs/package.md) - [MCP for your website](https://developers.blanxer.com/api-docs/mcp-for-website.md) · [Testing](https://developers.blanxer.com/api-docs/testing.md) · [Deploy to Cloudflare](https://developers.blanxer.com/api-docs/deploy-cloudflare.md) · [Troubleshooting](https://developers.blanxer.com/api-docs/troubleshooting.md) - [OpenAPI spec](https://developers.blanxer.com/openapi.yaml) for every endpoint a site uses --- # Quickstart BlanxerAPI lets you build a custom Next.js website for a Blanxer store and deploy it to the merchant's own Cloudflare account. Blanxer stays the admin: products, stock, orders, payments, delivery and SEO data live in Blanxer. The website is only the front end. The merchant usually starts with one line to an AI agent: > Build my Blanxer store website in Next.js and deploy it to my Cloudflare account. Follow https://developers.blanxer.com/llms.txt My store is `.blanxer.io`. This page is the procedure. Each step links to the guide with the details. ## Before you start Read [the 13 hard rules](https://developers.blanxer.com/api-docs/rules.md). In short: Next.js only, start from the starter, keep `@blanxer-dev/storefront` for checkout, keep the four required routes, call orders and payments from the browser, no secrets, no customer login, no invented data. Install the agent tools: - **Claude Code skill:** `/plugin marketplace add blanxer-dev/blanxer-agent-skills` then `/plugin install blanxer-website@blanxer` - **Blanxer MCP:** `claude mcp add --transport http blanxer https://mcp.blanxer.com/mcp` (the merchant signs in to Blanxer in the browser) - **Cursor, Codex, claude.ai:** add `https://mcp.blanxer.com/mcp` as a remote MCP server. See [MCP for your website](https://developers.blanxer.com/api-docs/mcp-for-website.md). The starter's `AGENTS.md` holds the same procedure as the skill. ## Three channels, three jobs | Channel | Used by | For | Auth | |---|---|---|---| | Public API, `https://api.blanxer.com` | The site (server and browser) | Read store, theme, catalog, delivery table, coupons. Place orders, start payments, track orders. | None. CORS `*`. | | Blanxer MCP, `https://mcp.blanxer.com/mcp` | You, the agent, in chat | Change store data: SEO text, products, photos, categories, brands, coupons, delivery, the site link | OAuth. The merchant signs in. | | Blanxer-served XML, `https://api.blanxer.com/public/...xml` | Google and Meta | Product feed and catalog sitemap | None | The site never holds a key and never talks to the MCP. ## The steps Confirm each step with the merchant before moving on. ### 1. Find the store and connect Look the store up by subdomain (or custom domain): ```bash curl -s "https://api.blanxer.com/store/check_domain?domain=mystore" ``` You get the store config, including `_id` (the store id every other call needs), `name`, `plan`, `addons`, `checkout`, `customization` and `categories`. An unknown domain returns HTTP 400 `{"message":"Domain not in use"}`. Field by field: [Store and theme](https://developers.blanxer.com/api-docs/store-and-theme.md). Show the merchant: - the store name and plan; - the product count (`GET /product/public/` returns all active products); - the payment methods the checkout will offer (see [Checkout → Payment methods](https://developers.blanxer.com/api-docs/checkout.md#payment-methods)); - **Free plan** (`plan` not one of `basic`, `premium`, `plus`, `platinum`): the checkout is Cash on Delivery only; - **Store with customer login turned on** (`customer_program.enabled`): the custom site still uses guest checkout. BlanxerAPI has no login. Then connect the Blanxer MCP, have the merchant sign in, and run `blanxer_audit_seo`. Also check the catalog for products with no photo, no price, no category or no SEO text. Show the gaps. ### 2. Design brief Ask for reference sites, the look, the pages and the tone. Use the store's logo, colours and font as defaults (`customization.brand_logo`, `customization.theme`, `customization.font`). ### 3. Scaffold from the starter ```bash npx degit blanxer-dev/blanxer-storefront-starter my-store cd my-store cp .env.example .env # set BLANXER_STORE= npm install ./node_modules/.bin/next dev ``` `BLANXER_STORE` is the subdomain (required). Optional: `BLANXER_API` (default `https://api.blanxer.com`), `SITE_URL` (the site's public origin; default the link saved in Blanxer) and `NEXT_PUBLIC_BLANXER_IMAGE_LOADER` (`wsrv`, `cloudflare` or `none`). See [Deploy → Configuration](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#configuration). Open `http://localhost:3000` and show the merchant the starter running with their real products before changing the design. The starter's `npm run dev`, `npm run build` and `npm run deploy` scripts do the same as the direct commands on this page. The direct `./node_modules/.bin/...` form avoids surprises when the machine has another Node install on its path. ### 4. Build - Build pages with the package's data functions and components. See [Catalog](https://developers.blanxer.com/api-docs/catalog.md) and [Package](https://developers.blanxer.com/api-docs/package.md). - Theme the checkout; don't rewrite it. See [Checkout](https://developers.blanxer.com/api-docs/checkout.md). - Optimise every image (rule 11) and show a before/after size table. See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md). - Fix store data through the MCP: SEO text, categories and brands for the menus, product photos, launch coupons. Confirm bulk changes first (rule 13). Routes every site has: `/` · `/products` · `/product/[slug]` · `/collections/[slug]` (including `new-arrivals`) · `/brand/[slug]` · `/brands` · `/search?q=` · `/sale` · `/cart` · `/checkout` · **`/payment/success`** · **`/payment/failed`** · **`/track/[id]`** · `/forms/[slug]` · `/blogs` (and `?category=`) · `/blog/[slug]` · `/sitemap.xml` (index) · `/sitemap-catalog.xml` · `/robots.txt` No `/account`, `/login` or `/p/[slug]`. ### 5. Check ```bash ./node_modules/.bin/next build npx blanxer-storefront check # add --lighthouse http://localhost:3000 with the production build running ``` It checks the routes, secrets, login code, that order and payment calls run in the browser, the image budget (and warns when a page has no main image marked with `preload`), and with `--lighthouse ` the speed (mobile ≥ 90, LCP < 2.5 s on home, a product and checkout; needs `next start` running). Fix every failure before deploying, or tell the merchant why one can't be fixed. ### 6. Test the checkout See [Testing](https://developers.blanxer.com/api-docs/testing.md). On the merchant's real store, test orders use the phone number `0000000000`: the API validates the order and returns `{"success":true}` **without creating it**. The checkout then shows "Test order accepted" and stops. That tests the form, validation, delivery charges, COD per place and coupons. Because no order exists, the `0000000000` order can't open a gateway or a QR screen. Check that every payment method the store has on appears for a COD and a non-COD place, and that `/payment/success`, `/payment/failed` and `/track/` render. The gateway and QR screens themselves are checked once, live, in step 12 (see [Testing → The live check](https://developers.blanxer.com/api-docs/testing.md#4-the-live-check)). ### 7. Sign in to Cloudflare ```bash npx wrangler login ``` The merchant signs in to **their own** Cloudflare account in the browser. Before the first deploy, rename the Worker in `wrangler.jsonc` (`name` and the matching `WORKER_SELF_REFERENCE` service) to the merchant's site name. Check the Worker size: 3 MiB (compressed) on the free plan. See [Deploy to Cloudflare](https://developers.blanxer.com/api-docs/deploy-cloudflare.md). ### 8. Deploy ```bash ./node_modules/.bin/opennextjs-cloudflare build && ./node_modules/.bin/opennextjs-cloudflare deploy ``` Print the live `*.workers.dev` link and open it. ### 9. Link the site to Blanxer Call `blanxer_set_storefront_url { url }`. It returns a preview and a `confirm_token`; show the merchant, and after their yes call `{ dry_run: false, confirm_token }`. (Or the merchant pastes the link in the Blanxer dashboard → avatar menu → **BlanxerAPI** → Your website, rolling out.) Blanxer then uses the site in the tracking link it generates, the delivered email, flash-sale alerts, the product feed and the sitemap. Register the feed with Meta and submit the sitemap to Google Search Console. See [SEO and tracking](https://developers.blanxer.com/api-docs/seo-and-tracking.md). ### 10. Custom domain (optional) Add it in Cloudflare, then update the link (step 9). ### 11. Retire the subdomain site (optional, merchant's choice) Only after step 9. Every page on `_{.blanxer.io` then shows a placeholder, **including tracking links sent before today**. See [Deploy to Cloudflare → Retiring the old subdomain site](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#retiring-the-old-subdomain-site).

### 12. Live check

On the live site open home, a product, checkout, the three payment/tracking pages and a real `/track/`. With the merchant's OK, place one real COD order and have the merchant cancel it in the dashboard. For one online method, start a real order, open the gateway or QR screen and stop without paying (closing the QR releases the hold), then cancel it in the dashboard. Hand over a README that says how to edit and redeploy.

## Next

- [Checkout](https://developers.blanxer.com/api-docs/checkout.md) is the most important page. Read it before touching `/checkout`.
- The API spec for every endpoint a site uses: [openapi.yaml](https://developers.blanxer.com/openapi.yaml).

---

# The 13 hard rules

These rules apply to every BlanxerAPI website. Read them before writing any code, and follow them on every step. They are the same rules the `blanxer-website` skill and the starter's `AGENTS.md` state first.

1. **Next.js only:** TypeScript, App Router. If asked for another framework, say BlanxerAPI supports Next.js and continue in Next.js.
2. **Start from `blanxer-storefront-starter` and keep `@blanxer-dev/storefront`.** Restyle the checkout through theme props and wrappers. **Never rewrite** the payment, delivery, coupon or order logic, and never call payment endpoints directly. The checkout's **"Checkout Powered by Blanxer"** line under the place-order button ("Blanxer" links to https://blanxer.com) is part of it: restyle it through `.bx-powered-by`, never remove or hide it.
3. **Required routes:** `/checkout`, `/payment/success`, `/payment/failed` and `/track/[id]`, at these exact paths.
4. **Send the site's own origin as `url`.** The package does it; never hardcode it.
5. **Browser-only calls:** orders, coupons, payment starts, hold release, back-in-stock, forms, cancel and review go from client components. Never from server code, route handlers or server actions.
6. **No secrets in the site.** No `sk_` key, MCP token, dashboard login or gateway key in code, `.env` or the build. Never ask the merchant to paste a key. Store changes go through the Blanxer MCP.
7. **No customer login.** No `/customer/auth/*` calls, and no account, login, wishlist or rewards pages.
8. **Don't invent data.** Prices, stock, delivery and payment methods come only from the API. No sample products or placeholder prices.
9. **Payment methods come from the store's settings** via the package. Never add or remove them by hand.
10. **Use our URL paths** (`/product/[slug]`, `/collections/[slug]`, `/brand/[slug]`), because the feed and sitemap use them. **Don't build a product feed or catalog sitemap**; Blanxer serves both. Only add the site's own extra pages to the sitemap index.
11. **Optimise every image before it goes into the site.**
- Use `npx blanxer-storefront images`:
- resize to the largest size shown ×2 (hero 2560 px, banner 1600, card 800);
- export AVIF + WebP at ~75 quality;
- strip EXIF and location data;
- use SVG for logos when available.
- Never commit originals.
- Load with `next/image`: each page's main (LCP) image gets `preload`, the rest load lazily with correct `sizes`.
- **Product photos go into Blanxer through the MCP, never into the site.**
- No autoplay video backgrounds or GIF banners unless the merchant insists after hearing the speed cost.
- Fonts go through `next/font`, at most 2 families.
12. **The site's design lives in the site.** Don't use MCP page-builder tools for a custom site. Use the MCP only for store data.
13. **Confirm before bulk store changes.** Show the list (SEO for many products, imports, delivery charges) and get a yes. The MCP's own confirmations still apply.

## Why these rules exist

| Rule | What breaks without it |
|---|---|
| 2, 9 | The checkout drifts from Blanxer's: wrong totals, missing gateways, orders the server refuses. |
| 2 (Powered by) | The "Checkout Powered by Blanxer" line is a condition of using Blanxer's checkout on a custom site (owner decision, 2026-10-11). The package has no prop to turn it off. |
| 3, 4 | Gateways return the shopper to `/payment/success` or `/payment/failed`, and the confirmation email links to `/track/`. A missing page means a 404 **after the shopper paid**. |
| 5 | Order creation is limited to 5 per 10 minutes per store and IP. Every Cloudflare Worker shares a few IPs, so server-side orders would block each other. The Meta relay also uses the caller's IP. |
| 6 | The site is public code on the merchant's account. Anything in it is readable. The public API needs no key. |
| 7 | Customer accounts are not part of BlanxerAPI. Custom sites use guest checkout. |
| 10 | Blanxer's product feed and sitemap link to `/product/`, `/collections/` and `/brand/` on the site. Other paths turn every feed and sitemap link into a 404. |
| 11 | Image weight is the main reason a store site is slow. See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md). |
| 12 | Page-builder tools change the Blanxer-hosted site, not the custom site. |
| 13 | Bulk changes touch live store data shared with the Blanxer dashboard, POS and app. |

---

# Store and theme

One call returns everything about the store that a site needs to look like the store: name, logo, colours, font, categories, menus, social links, checkout settings, payment add-ons and tracking plugins.

## Looking up the store

```bash
curl -s "https://api.blanxer.com/store/check_domain?domain=mystore"
```

- `domain` is the store's subdomain (`mystore` for `mystore.blanxer.io`) or its custom domain (`shop.example.com`). It is lower-cased.
- `POST /store/check_domain` with `{"domain": "mystore"}` returns the same.
- An unknown domain: HTTP 400 `{"message":"Domain not in use"}`. A missing `domain`: HTTP 400 `{"fields":{"domain":"Domain is required"}}`.
- The API caches the answer for 1 hour and clears it when the merchant changes store settings. The cache is per API process, so on a multi-process deployment an old answer can still be served for up to 1 hour. The package adds a 60-second cache on top.

In the site: `getStore()` and `getStoreId()` from `@blanxer-dev/storefront/server` read `BLANXER_STORE` and make this call. **`_id` is the `store_id` every other endpoint needs.**

## What it returns

| Field | What it is |
|---|---|
| `_id` | Store id |
| `name`, `description`, `display_image` | Store name, one-line description, an image |
| `sub_domain`, `custom_domain` | `mystore`, and the Blanxer custom domain if any |
| `storefront_url` | The saved link to the custom site, `''` when none. See [Deploy → Link the site](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#link-the-site-to-blanxer). |
| `plan` | `''` (free), `pos`, `basic`, `premium`, `plus`, `platinum`. Online payments need `basic`, `premium`, `plus` or `platinum`. |
| `customization` | Logo, name, theme colour, font, currency label, top bar, popup, hero images (below) |
| `navigation`, `footer` | Menu items and footer content as set in Blanxer |
| `categories[]` | `_id`, `name`, `slug`, `image`, `order`, `seo_title`, `seo_description`, `seo_image`, `hide_on_product` |
| `blog_categories[]` | `name`, `slug`, `image`, `order`, SEO fields |
| `social` | `facebook`, `instagram`, `tiktok`, `whatsapp` |
| `compliance` | Business details for the footer: `business_name`, `business_address`, `pan`, `registration_number`, `ecommerce_number`, `contact`, `email`, `complain_officer`, `permits`, `outlets`, `exim_code`. Show them only when `compliance.style === 'show'` |
| `checkout` | Which checkout fields are on. See [Checkout → Fields](https://developers.blanxer.com/api-docs/checkout.md#fields). |
| `addons`, `setting` | Payment add-ons, and store settings. The payment-credential keys in `setting` are masked to `'yes'` / `''`; other keys (delivery settings and more) come as stored. See [Checkout → Payment methods](https://developers.blanxer.com/api-docs/checkout.md#payment-methods). |
| `plugins[]` | `{name, details}`: tracking tags and small features (below) |
| `use_advanced_inventory` | Stock is per outlet. See [Catalog → Stock](https://developers.blanxer.com/api-docs/catalog.md#stock). |
| `customer_program` | `{enabled, loyalty_enabled, membership_enabled, back_in_stock: {enabled}, login}` |
| `under_construction` | `off`, `sub`, `cus` or `both`. Controls the **Blanxer-hosted** site only. Ignore it in a custom site. |
| `kyc_status`, `blanxer_pay`, `loyalty`, `current_template` | Not needed by a custom site |

### Don't use

- `customer_program.enabled` turns on customer accounts on the Blanxer-hosted site. A custom site has no login (rule 7) and uses guest checkout either way. Use only `customer_program.back_in_stock.enabled`.
- `setting` holds store configuration. Only test the masked payment keys listed in the checkout guide, for truthiness. Don't display, log or depend on any other value in it.
- `customization.page_styles`, `customization.current_template`, `customization.selected_navbar` and `customization.selected_hero` are layout choices for the Blanxer-hosted site. A custom site ignores them.

## Brand and theme

From `customization`:

| Field | Use | Default when empty |
|---|---|---|
| `brand_name` | Store name in the header, titles, JSON-LD | `name` |
| `brand_logo` | Logo URL | Show the name as text |
| `favicon` | Favicon URL | Your own |
| `theme` | Primary colour (below) | `violet` |
| `font` | A Google Fonts family name, e.g. `Poppins` | `Poppins` |
| `currency_indicator` | Currency label before prices | `Rs.` (the package's default) |
| `image_ratio` | The shape new product photos are cropped to on upload: `1` = 1:1, `2` = 4:5, `3` = 9:16. Use it for product card frames. Older photos may have other shapes, so use `object-fit` | 1:1 |
| `top_bar_text`, `top_bar_goto` | Announcement bar text and link | No bar |
| `top_bar_ui` | Announcement bar style: `default`, `marquee` or `scallop` | `default` |
| `popup_image`, `popup_goto` | A promo popup image and its link. The hosted storefront shows it on the home page only, once per browser session (`sessionStorage['homepageBannerShown']`) | No popup |
| `hero_images[]`, `hero_taglines[]`, `hero_links[]` | Home hero slides (image, tagline, link, by index) | Design your own |

The `top_bar_color` plugin, when present, gives the bar's colours: `details: {bg, text}`. Without it, the hosted storefront uses shade 800 of the primary palette as the bar's background.

These are **defaults** for the design brief. The merchant may want a different look; the site's design lives in the site (rule 12). If they want the shared brand values changed (also on the Blanxer-hosted site and in emails), use `blanxer_update_store_profile` / `blanxer_update_appearance` through the MCP.

### Theme colour

`customization.theme` is either a palette name or `custom#RRGGBB`.

- **`custom#RRGGBB`**: the merchant picked their own colour. The hex is shade 500 of a palette the hosted storefront derives from it; its buttons use the derived shade 600, so they look a little darker than the hex. The package uses the hex itself as `--bx-primary`.
- **A name**: one of the palettes below (10 shades, 50 → 900). The Blanxer storefront's buttons use shade 600, hover 700.

| `theme` | Shade 50 | Shade 600 (buttons) | Shade 900 |
|---|---|---|---|
| `dark` | #C9C9C9 | #2e2e2e | #141414 |
| `gray` | #f8f9fa | #868e96 | #212529 |
| `red` | #fff5f5 | #fa5252 | #c92a2a |
| `oliz_red` | #fef2f2 | #db272a | #7f1d1f |
| `pink` | #fff0f6 | #e64980 | #a61e4d |
| `baby_pink` | #fff7fa | #ffa5c2 | #f9739e |
| `grape` | #f8f0fc | #be4bdb | #862e9c |
| `violet` | #f3f0ff | #7950f2 | #5f3dc4 |
| `indigo` | #edf2ff | #4c6ef5 | #364fc7 |
| `blue` | #e7f5ff | #228be6 | #1864ab |
| `cyan` | #e3fafc | #15aabf | #0b7285 |
| `teal` | #e6fcf5 | #12b886 | #087f5b |
| `green` | #ebfbee | #40c057 | #2b8a3e |
| `lime` | #f4fce3 | #82c91e | #5c940d |
| `yellow` | #fff9db | #fab005 | #e67700 |
| `orange` | #fff4e6 | #fd7e14 | #d9480f |
| `brown` | #f6f4f0 | #816a4d | #4e3e35 |
| `blanxer_purple` | #f6f2ff | #8830f7 | #54169c |
| `blanxer_red` | #fff1f2 | #ed1520 | #88141a |
| `blanxer_blue` | #eff8ff | #007ace | #084572 |
| `blanxer_green` | #eefff5 | #01b859 | #0a5d35 |

Map the primary colour to a CSS variable (the name below is an example) and pass it to the package components through their `theme` prop or CSS variables:

```tsx
// app/layout.tsx
import { getStore } from '@blanxer-dev/storefront/server';

const NAMED: Record = { violet: '#7950f2', blue: '#228be6' /* ...from the table */ };

export default async function RootLayout({ children }: { children: React.ReactNode }) {
const store = await getStore();
const t = store.customization?.theme || 'violet';
const primary = t.startsWith('custom#') ? t.slice(6) : NAMED[t] ?? NAMED.violet;
return (

{children}

);
}
```

### Font

Load the store's font with `next/font/google`, not a `` to Google Fonts (rule 11: at most 2 families, self-hosted, no layout shift):

```tsx
import { Poppins } from 'next/font/google';
const font = Poppins({ subsets: ['latin'], weight: ['400', '600'], display: 'swap' });
```

`next/font` needs the family at build time. Read `customization.font` once while scaffolding, and change the import if the merchant changes the font later.

## Menus and footer

- `navigation.items` is a list of `{n, g, i, l?}`: `n` the label, `g` the link, `i` the children (same shape, for dropdowns), `l` an optional section logo. `navigation.style` (default `LC`) and `navigation.extras` (may hold `socialLinks` and `contextual_nav`) are Blanxer layout settings; a custom site may ignore them.
- `footer.details` holds the footer content the merchant set. Its shape depends on `footer.style` (one per Blanxer footer layout), so inspect it for the store you are building.
- Restyle both freely. Keep the merchant's labels and links.
- **Links to `/p/`** are Blanxer page-builder pages. Custom sites don't have them (and Blanxer's sitemap leaves them out once the site link is saved). Ask the merchant what each should become, or leave it out.
- Other links use the same paths as a custom site: `/products`, `/collections/`, `/product/`, `/brand/`, `/brands`, `/sale`, `/search`, `/blogs`, `/blog/`, `/forms/`. Only `https://` links are external.
- If `compliance.style === 'show'`, show the compliance details in the footer: Nepali e-commerce stores usually display their business name, address, PAN/registration and complaint officer.
- `categories`, brands and other lists come in the order they are stored. Sort categories by `order` in the site.

## Plugins

`plugins` is a list of `{name, details}`. The ones a custom site uses:

| `name` | `details` | Use |
|---|---|---|
| `meta_tags` | `[{n, c}]`: `` | Search Console verification and other verification tags. See [SEO and tracking](https://developers.blanxer.com/api-docs/seo-and-tracking.md#search-console-verification). |
| `ga` | `"G-XXXXXXXXXX"` | Google Analytics 4 |
| `gtm` | `"GTM-XXXXXXX"` | Google Tag Manager |
| `fb_pixel` | Pixel id | Meta Pixel |
| `meta_capi` | `true` | The store has Meta Conversions API on; relay events (the token stays on the server) |
| `clarity` | Project id | Microsoft Clarity |
| `whatsapp_chat` | `{phone}` | WhatsApp chat button |
| `tawk` | `{p, w}` | Tawk.to chat: property and widget id |
| `top_bar_color` | `{bg, text}` | Announcement bar colours |
| `product_custom_options` | `{showProductStock, outOfStockBaseValue, discountBadgeColor, ...}` | Stock display and the discount badge colour on product pages |
| `newsletter` | `{enabled, headerImage, title, description, list_id}` | A newsletter sign-up block |
| `samparka` | `{enabled: true}` | The store uses Samparka (loyalty); custom sites have no login, so ignore it |

Most delivery-partner plugins are removed from this payload. Treat any other plugin as Blanxer-internal: don't display, log or depend on its `details`.

## Product fields for the product page

Besides the catalog fields (see [Catalog](https://developers.blanxer.com/api-docs/catalog.md#one-product)), the product response has:

- `color_name` and `size_name`: the labels for the two option pickers. Defaults: "Choose Variant" and "Choose Size".
- Colour swatches only when a colour carries a code (`"Maroon:#7a1f2b"`); otherwise show the name.
- `print_addon`: the print add-on, which the package can't sell yet (see [Checkout → Print add-on products](https://developers.blanxer.com/api-docs/checkout.md#print-add-on-products)).
- `desc_page` (also on categories and brands): a page-builder description block for the Blanxer-hosted site. A custom site uses the HTML `description` / `long_description` instead.
- `categories[].hide_on_product` (in `check_domain`): don't list that category on product pages.

## The site's own origin

- In the browser, the site's origin is `window.location.origin`. The checkout sends it as `url` (rule 4).
- On the server (metadata, JSON-LD, sitemap index, robots), use `siteOrigin()` from the package: the `SITE_URL` env, else the store's saved `storefront_url`, else the request host. Pages that should stay static pass `{ fromRequest: false }` (then it returns `''` instead of reading the request).
- `storefront_url` is what Blanxer uses for links it sends. It changes only when the merchant saves the site link in Blanxer (not when a custom domain is added). Don't hardcode it in the site.

---

# Catalog

Products, variants, stock, categories, brands, search, sale and flash sales. All catalog reads are public `GET`s on `https://api.blanxer.com` with no key. In the site, read them on the server through `@blanxer-dev/storefront/server` (60-second cache, normal `User-Agent`). Never put sample products or placeholder prices in the site (rule 8).

## Endpoints

| What | Endpoint | Returns |
|---|---|---|
| All products | `GET /product/public/` | Array of list items, every Active, non-POS product. Not paginated. |
| A page of products | `GET /product/p/public/?page=1&per_page=30&sort_by=created_at&sort_order=desc` | `{success, meta, products}` |
| One product | `GET /product/public//` | Full product (see below). `` may also be the product `_id`. |
| A category | `GET /product/public//category/` | `{category, products}` |
| New arrivals | `GET /product/public//category/new-arrivals` | `{category: {_id: 1, name: "New Arrivals", slug: "new-arrivals"}, products}`: up to 12 of the newest products |
| Search | `GET /product/public/search/?q=` | Array of list items, up to 50 |
| On sale | `GET /product/public/sale/` | Array of list items |
| All brands | `GET /brand/public/all/` | `{brands}` |
| A brand's products | `GET /brand/public/products//` | `{brand, products}` |
| A brand's details | `GET /brand/public/details//` | `{brand, page}` |
| Flash sales | `GET /public/flash-sale/` | `{server_time, sales}` |
| One product's flash sale | `GET /public/flash-sale//product/` | `{server_time, sale, units}` |

Categories are not an endpoint: they come with the store in `check_domain.categories` (see [Store and theme](https://developers.blanxer.com/api-docs/store-and-theme.md)).

There is also `GET /product/public/barcode/?code=` (looks a product up by barcode). A custom site rarely needs it.

Errors:

- HTTP 400 `{"message": "..."}`: `Product not found`, `Category not found`, `Brand not found`.
- HTTP 400 `{"error_type":"zod_validation","fields":{...}}` for a malformed id on search, sale, the paged list, brands and flash sales.
- HTTP 500 `{"errors":{"message":"Cast to ObjectId failed..."}}` for a malformed `store_id` on all products, a category and one product. Always pass the `_id` from `check_domain`.
- A well-formed but unknown store id is not an error: `[]` from the lists, `{category: false, products: []}` from a category.

### Server-side caching

- The API caches only three catalog reads for up to 1 hour: all products, the paged list and a category (new arrivals included). It also caches `check_domain`. It clears them when the merchant changes the store's products, categories or settings.
- Orders don't clear the cache, so stock and `in_stock` in those lists can be up to 1 hour old. The product page and the server's order check always use current stock.
- Product detail, search, sale and brands are not cached by the API.
- The package adds `next: { revalidate: 60 }`. Store changes show on the site within about a minute, without a redeploy.

## List items

Every list endpoint (all products, page, category, search, sale, brand products, similar products) returns this item shape. Each loads a slightly different set of fields; the differences are listed below the example.

```json
{
"_id": "66f1c0ffee0000000000aa01",
"name": "Pashmina Shawl",
"slug": "pashmina-shawl",
"price": null,
"min_price": 2500,
"max_price": 3200,
"compare_at_price": 0,
"has_variants": true,
"in_stock": true,
"quantity": 14,
"total_variants": 6,
"channel": 1,
"variants": [{ "price": 2500, "compare_at_price": 0, "quantity": 4, "inventory_summary": [] }],
"total_rating": 18,
"review_count": 4,
"image_urls": ["https://.../shawl-1.jpg"],
"status": "Active",
"colors": ["Maroon:#7a1f2b", "Cream"],
"sizes": ["Standard", "Large"],
"tags": ["new"],
"categories": ["Shawls"],
"created_at": "2026-09-30T10:12:00.000Z",
"release_date": null,
"brand": { "_id": "...", "name": "...", "slug": "...", "logo": "..." }
}
```

- **Price:** a product without variants has `price`. A product with variants has either `price` or `min_price` / `max_price` with `price: null`. Show "Rs 2,500 – 3,200" for a range. `price` is set (and min/max are null) when all variants cost the same, and also when any variant's price is 0 or missing; then `price` is the highest variant price.
- **`compare_at_price`** above the price means the product is discounted; show it struck through.
- **`categories`** here are category **names**, not ids. Exception: on the category endpoint (not new arrivals) they are `{_id, name, slug}` objects.
- **`brand`** is `{_id, name, slug, logo}` on the category, new-arrivals and sale endpoints, and `{name, slug, logo}` (no `_id`) on search. All products, the paged list, brand products and similar products leave it out. It is never a plain id.
- **`quantity`:** with variants, the sum of the positive variant stock; without variants, the product's own quantity (it can be 0 or below).
- **`variants`** carry `price`, `compare_at_price`, `quantity` and `inventory_summary`. Only search results add `_id` and `option_name`. Get variant ids from the product endpoint.
- **Differences per endpoint:**
- category, new arrivals, search and similar products don't load `continue_selling`, so their `in_stock` is stock only;
- `release_date` is only on category, search and brand products;
- search results have no `total_rating` / `review_count`, and add `score` (relevance);
- similar products have no `channel`.
- **Rating:** `total_rating` is a sum. Average = `total_rating / review_count`.
- **`in_stock`** is described under [Stock](#stock).

### The paged list

`GET /product/p/public/`:

| Param | Default | Values |
|---|---|---|
| `page` | 1 | ≥ 1 |
| `per_page` | 30 | ≥ 1; values above 100 are treated as 100 |
| `sort_by` | `created_at` | `created_at`, `price`, `compare_at_price`, `name`, `total_rating`, `review_count`, `quantity` |
| `sort_order` | `desc` | `asc`, `desc` |

```json
{ "success": true,
"meta": { "page": 1, "per_page": 30, "total": 212, "total_pages": 8, "sort_by": "created_at", "sort_order": "desc" },
"products": [ ... ] }
```

`sort_by=price` sorts on the stored top-level price, which is 0 for many products with variants. For a correct price sort, load all products and sort in the site by `price ?? min_price`.

### Search

- `q` must be at least 3 characters; shorter queries return `[]` (no error).
- It is an autocomplete search over a key built from the product name, its category names, colours, sizes and tags (tags containing `:` are left out). Best match first, Active and non-POS only.
- The limit of 50 is applied **before** the Active/non-POS filter, so a search can return fewer than 50 even when more products match. (One store has a higher limit.)

### Sale

`/product/public/sale/` returns Active, non-POS products with a `compare_at_price` above 0 on the product or on any variant. (Before the BlanxerAPI backend release it returned `[]` on stores with advanced inventory.)

## One product

`GET /product/public//` returns the stored product plus a few extras:

| Field | Notes |
|---|---|
| `_id`, `name`, `slug`, `status`, `channel` | See the warning below |
| `description`, `long_description` | **HTML** from Blanxer's editor. Sanitize before rendering. |
| `price`, `compare_at_price`, `quantity`, `weight`, `sku`, `barcode`, `continue_selling` | Product-level values. For a product with variants, use the variant's. |
| `colors`, `sizes` | Empty when the product has no variants |
| `variants[]` | `_id`, `option_name`, `price`, `compare_at_price`, `quantity`, `sku`, `weight`, `image_url`, `barcode`, and also `alt_barcode`, `exim_code`, `tigg_id`, `inventory_summary` |
| `image_urls[]` | Absolute image URLs |
| `categories[]` | Category **ids** (match them against `check_domain.categories`) |
| `brand` | `{_id, name, slug, logo}` or missing |
| `tags[]` | See [Tags](#tags) |
| `custom_fields` | Inputs the shopper fills; see [Checkout → Custom fields](https://developers.blanxer.com/api-docs/checkout.md#custom-fields) |
| `seo_title`, `seo_description`, `seo_image` | See [SEO and tracking](https://developers.blanxer.com/api-docs/seo-and-tracking.md) |
| `total_rating`, `review_count`, `reviews[]` | Reviews: `rating`, `review`, `images`, `customer_name`, `verified_purchase`, `created_at`, newest first |
| `similar_products[]` | List items: Active only, but may include POS-only products; no `channel` |
| `csrf_token` | Send with custom-field image uploads (accepted, but not checked by the server today) |
| `release_date`, `created_at`, `updated_at` | |

> **Warning: this endpoint also returns non-Active and POS-only products.** `status` is `Active`, `Draft` or `Archived` (`''` when never set). Your product page must show a 404 unless `status === 'Active'` and `channel !== 3`. The package's `getProduct()` already returns `null` for those:
>
> ```ts
> import { notFound } from 'next/navigation';
> const product = await getProduct(params.slug); // @blanxer-dev/storefront/server
> if (!product || product.status !== 'Active' || product.channel === 3) notFound();
> ```
>
> An unknown slug is HTTP **400** `{"message":"Product not found"}`, not 404. Treat it as not found.

`channel`: 1 = website and POS, 2 = website only, 3 = POS only.

## Variants

A product has variants when `variants.length > 0`. Its options are `colors` and/or `sizes`.

### Option names

Each variant's `option_name` is built from the options:

| Product has | `option_name` |
|---|---|
| Colours and sizes | `"/"`, e.g. `"Red/XL"` |
| Sizes only | `""` |
| Colours only | `""` |

- A colour may carry a swatch code after the **first** colon: `"Maroon:#7a1f2b"`, or a two-tone `"Black:#111111|#e8a200"`. The display name is the part before the colon. The `option_name` uses the display name (`"Maroon/Large"`).
- A colour or size name can contain `/`. Split an `option_name` against the known colour and size lists (longest colour first), not on the first slash.
- Not every colour/size pair has to exist. Offer only sizes that have a variant for the chosen colour; when the colour changes and the size isn't valid any more, pick the first valid size.

### From the shopper's choice to the order

```ts
function findVariant(product: Product, color: string, size: string) {
const colors = product.colors.map((c) => c.split(':')[0]);
const name =
colors.length && product.sizes.length ? `${color}/${size}` :
product.sizes.length ? size :
colors.length ? color : '';
return product.variants.find((v) => v.option_name === name); // undefined = not sold
}
```

- Put the variant's **`_id`** in the cart line as `variant`. The order request needs the id, not the name (`Variant selection required for this product` otherwise).
- Show the variant's `price` (when set), `compare_at_price`, `image_url` (switch the gallery to it) and `sku`.
- The cart line's `weight` is the variant's `weight` when it is a number, else the product's.
- A product's top-level `price` is often 0 when it has variants. Never show it alone.

## Stock

### Simple stores

- Out of stock for a quantity `q`: `!continue_selling && stock < q`, where `stock` is the variant's `quantity` (or the product's for a simple product).
- `continue_selling` is `true` by default: the product sells even at 0 stock. Many stores keep it on.
- List items have `in_stock` = `continue_selling || quantity > 0` (or any variant > 0), except where `continue_selling` isn't loaded (category, new arrivals, search, similar products): there it is stock only. See [List items](#list-items) for `quantity`.

### Stores with advanced inventory

When `check_domain.use_advanced_inventory` is true and the store has a website outlet:

- every `quantity` the API returns is the **website outlet's** stock, not the total;
- list items' `in_stock` ignores `continue_selling` (`quantity > 0`), and the Blanxer storefront's product page does the same (out of stock = `stock < q`). Do the same. (The order check on the server still lets a `continue_selling` product through; showing it as out of stock is the safe side.)
- the brand-products endpoint does not apply the outlet's stock (it returns the global quantity). Prefer the product page's own check.

### What to show

- Out of stock: disable Add to cart and show the back-in-stock form when the store has it on. See [Forms and extras](https://developers.blanxer.com/api-docs/forms-and-extras.md#back-in-stock-alerts).
- The `product_custom_options` plugin (in `check_domain.plugins`) can ask for stock display: `details.showProductStock` (show "N in stock") and `details.outOfStockBaseValue` (show a low-stock warning at or below that number).
- The server makes the final check at order time, including units held in other shoppers' checkouts.

## Tags

`tags` is free text the merchant sets. A few have meaning in the Blanxer storefront:

| Tag | Meaning |
|---|---|
| `coming_soon` | Shown, but can't be bought yet; no back-in-stock form |
| `no_price` | The price is hidden |
| `team_order` | A team/bulk order product (Blanxer-specific form; not part of v1) |
| `rd__` | Replaces Add to cart with a button linking out; `+` in the label is a space |
| `ard__` | Adds an extra outlined button linking out, next to Add to cart. When a product has both, `rd_` wins on product cards |

## Categories

From `check_domain.categories`:

```json
{ "_id": "...", "name": "Shawls", "slug": "shawls", "image": "https://...", "order": 2,
"seo_title": "...", "seo_description": "...", "seo_image": "...", "hide_on_product": false }
```

- Sort by `order` for menus.
- `/collections/` uses `GET /product/public//category/`. It returns every product in the category (not paginated); paginate in the site if needed.
- The endpoint's `category` has only `_id`, `name`, `slug` and `desc_page`. Take the SEO fields and image from `check_domain.categories`.
- `new-arrivals` is a virtual category: the 12 newest products, minus any that aren't Active or are POS-only (so up to 12). It is always in Blanxer's sitemap, so keep `/collections/new-arrivals` working.

## Brands

- `GET /brand/public/all/` → `{brands: [{_id, name, slug, logo, page, desc_page, created_at, ...}]}` for `/brands`, newest first. Sort them in the site if you want another order.
- `GET /brand/public/products//` → `{brand: {name, slug, page: {seo_title, seo_description, seo_image}}, products}` for `/brand/`. Only Active, non-POS products.
- `GET /brand/public/details//` → `{brand, page}`, where `page` is the brand's page-builder page (or `null`). A custom site uses it only for the brand's SEO fields; it doesn't render page-builder sections.

## Flash sales

A flash sale is an offer campaign with a start and end time. While it is live, **Blanxer writes the offer price into the product's (or variant's) `price`**, and may set `compare_at_price` to the old price. So the catalog endpoints already return sale prices; the flash-sale endpoints add the countdown, limits and units left.

### What is on

`GET /public/flash-sale/` lists live sales and sales starting within 14 days:

```json
{ "server_time": "2026-10-11T08:00:00.000Z",
"sales": [{ "_id": "...", "name": "Dashain Flash", "status": "live",
"start_at": "2026-10-11T06:00:00.000Z", "end_at": "2026-10-11T10:00:00.000Z",
"discount_type": "percentage", "discount_value": 20, "max_per_order": 2,
"show_countdown": true, "show_stock_left": true, "sold_out": false }] }
```

`status` is `live` or `upcoming`. `discount_type` is `percentage`, `fixed_amount` or `fixed_price`. `max_per_order` 0 means no limit.

### One product

`GET /public/flash-sale//product/`:

```json
{ "server_time": "...", "sale": { "...same fields...": "", "offer_price_from": 999 },
"units": { "available": 3, "in_checkout": 2 } }
```

- `sale` is `null` when the product is in no live or upcoming sale.
- `offer_price_from` is the lowest offer price, for "Rs 999 from 10:00" before the sale starts. It is `null` when no offer price is set.
- `units` is missing when `sale` is `null`. Otherwise it is `null` unless the sale is live, `show_stock_left` is on and the product doesn't continue selling. It counts the whole product (all variants). `in_checkout` = units held in other shoppers' checkouts.

### How the strip behaves

The package's `FlashSaleStrip` does this:

- Correct the device clock with `server_time` (offset = `server_time − Date.now()`) and count down to `end_at` (live) or `start_at` (upcoming), when `show_countdown`.
- While live, refresh the product's sale every 15 seconds.
- Show "Only N left", plus "· N in checkout" when some are held. With 0 available but some in checkout: "All remaining units are in other shoppers' checkouts". Sold out when `sold_out` or no units at all.
- Cap the quantity picker at `max_per_order` while live. The server enforces it: `Flash sale: you can buy at most N of "" per order.`
- When the countdown reaches 0, reload the page about 20 seconds later; the backend flips the sale within a minute.
- For an upcoming sale, offer "Notify me" (below).

The site's 60-second cache can show the old price for up to a minute after a sale starts or ends. The server always charges the current price.

### Notify me when it starts

```http
POST /public/flash-sale//notify
{ "campaign_id": "...", "product_id": "...", "product_name": "...",
"url": "https://mystore.com/product/pashmina-shawl", "phone": "9800000000" }
```

- `phone` (10 digits) or `email` is required. Without both: HTTP 400 `{"error_type":"zod_validation","fields":{"phone":"A phone number or email is required"}}`.
- Only for scheduled sales: any other status gives `This sale has already started`. An unknown sale: `Sale not found`.
- `url` is kept only if it is on the store's own domains, including the saved site link (`storefront_url`). Save the site link in Blanxer, or the alert email has no link.
- Response: `{"success": true, "message": "We'll let you know when the sale starts."}`.
- Limit: 10 per 15 minutes per IP. Call it from the browser.

## Prices and currency

- Prices are in NPR. Format with `Intl.NumberFormat('en-IN')`.
- The store's currency label is `check_domain.customization.currency_indicator` (the package's default is `Rs.`).

## Product images

`image_urls` and variant `image_url` are absolute URLs on Blanxer's storage. Load them with `next/image` and the package's `blanxerImageLoader` so they are resized. Don't download product photos into the site (rule 11). See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md).

---

# Checkout

> **Use `@blanxer-dev/storefront`'s `Checkout` component. This page documents what it does.** Restyle it with theme props, CSS variables and wrappers (rule 2). Don't rewrite the payment, delivery, coupon or order logic, and don't call payment endpoints yourself. You need this page to theme the checkout safely, to debug it, and to explain it to the merchant.

The checkout behaves like the Blanxer-hosted storefront's checkout (storefront `main` at `cabd695`): the same fields, delivery places and charges, coupons, payment methods, stock holds, flash-sale limits and tracking. Where the package differs from the hosted storefront, this page says so. The hosted storefront also has a few store-specific checkout variants; the package doesn't port them.

The server re-checks the order. Prices, stock, delivery charges, COD and coupons are recomputed on the server; what the browser shows is a preview. Two things are taken from the request as sent: each line's `customization_charge` and its custom-field values.

## The flow at a glance

1. The page loads the store (`check_domain`) on the server. The delivery table is loaded on the server when you pass it to `Checkout` as `delivery` (the starter does); without it, the package fetches it in the browser.
2. The shopper fills the form, picks a delivery place and a payment method, and may apply a coupon.
3. The browser sends `POST /order/` with the cart lines, the form, the payment method, the coupon `_id` and `url` = the site's own origin.
4. The API creates the order. COD orders are `Pending` and stock is reduced at once. Online orders are `Inactive` and their units are held while the shopper pays.
5. **COD:** the browser goes to `/track/?from=checkout`.
**Redirect gateways** (eSewa, Khalti, FonePay, NPX, Nabil card): the browser starts the payment and leaves for the gateway. The gateway returns to the API, and the API redirects to `/payment/success` or `/payment/failed`.
**In-page QR** (Fonepay QR, Blanxer QR, Checkout by Fonepay): a QR modal opens with a hold timer. The browser polls for the payment, then goes to `/payment/success`.
6. `/payment/success` forwards to `/track/?from=checkout`.

Everything in steps 3–6 runs in the browser (rule 5).

## What the checkout needs

| Input | From | Notes |
|---|---|---|
| Store config | `GET /store/check_domain?domain=` | `_id`, `plan`, `addons`, `setting`, `checkout`. Load it on the server. (The hosted storefront uses `POST /store/check_domain?d=` with body `{domain}`; both return the same.) |
| Delivery table | `GET /public/delivery_charge/` | Load it on the server and pass it as `delivery`. |
| Cart lines | The browser, `localStorage['cart_items']` | Only the selected lines are ordered (`localStorage['cart_selection']`). |
| `url` | `window.location.origin` | No trailing slash. Never hardcode it (rule 4). |

### A cart line

```ts
interface CartLine {
id: string; // `${product}_${variant}` (see below)
product: string; // product _id
variant: string; // variant _id, '' for a product without variants
quantity: number;
product_name: string;
variant_name: string; // the variant's option_name, e.g. "Red/XL"
price: number; // display only; the server uses its own price
compare_at_price: number;
weight: number; // kg, per unit: the variant's weight if it is a number, else the product's
image_url: string;
sku?: string;
custom_fields: string[]; // serialized, see "Custom fields"
customization_charge?: number; // per unit, from paid custom fields
}
```

- **Line id:** `${product}_${variant}`. Adding the same product and variant again adds to that line's quantity, even when the custom-field values differ; the line keeps its first values. Only team-order adds (`addManyToCart`) give each line with custom fields its own id. The hosted storefront also gives print lines their own id (`_${printId}` appended).
- **Storage keys** match the hosted storefront (`cart_items`, `cart_selection`, `promo_code`, `checkout_order_id`, `pixel_purchase_pending`), except back-in-stock: the package uses `stock_alerts`, the hosted storefront `bx_stock_alerts`.

## Fields

Field names are the keys of the order request body. "Server" is the backend's zod schema for `POST /order/:store_id`.

| Field | Shown | Required | Browser check | Server rule |
|---|---|---|---|---|
| `customer_full_name` | Always | Yes | Not empty | 2–120 characters |
| `customer_phone_number` | Always | Yes | `/^[0-9]{10}$/` | Exactly 10 characters: `Phone number must be of 10 digit` |
| `customer_alt_phone_number` | Always, labelled optional | No | Empty, or `/^[0-9]{10}$/` | Empty or 10 digits: `Alternate phone number must be of 10 digit` |
| `customer_email` | Always | When `checkout.extras.email_required` | Valid email when required | Valid email or `''`. Lower-cased; a trailing `.con` becomes `.com`. Missing when required: HTTP **401** `{"fields":{"customer_email":"Email address is required"}}` |
| `customer_address_city` | Always (the delivery place select) | Yes | Not empty | 2–320 characters, and must equal a place name in the delivery table |
| `customer_address` | Always | Yes | Not empty | 2–320 characters |
| `customer_address_landmark` | Always | No | — | ≤ 320 characters |
| `order_note` | Always | No | — | ≤ 320 characters: `Max 320 character is allowed` |
| `sender_full_name` | When `checkout.receiver_info` | Yes, when shown | Not empty | ≤ 200 characters |
| `sender_phone_number` | When `checkout.receiver_info` | Yes, when shown | `/^[0-9]{10}$/` | ≤ 15 characters |
| `sender_email` | When `checkout.receiver_info` | When `checkout.extras.sender_email_required` | Valid email when required | Valid email or `''`. Missing when required: HTTP **401** `{"fields":{"sender_email":"Sender email address is required"}}` |
| `company_name` | When `checkout.pan` | No | — | ≤ 50 characters |
| `pan` | When `checkout.pan` | No | — | ≤ 9 characters |
| `delivery_date` | When `checkout.estimated_delivery` | No | Date input, minimum today | Optional string; sent as `YYYY-MM-DD` |

Layout rules the component follows:

- With `checkout.receiver_info` on, the form has "1. Sender Information" (the `sender_*` fields) and "2. Receiver Information" (the `customer_*` fields plus the delivery place and address). The receiver is the person the parcel goes to.
- **Confirmation email:** when `sender_full_name` is set, it goes only to `sender_email`, and to nobody when that is empty. Otherwise it goes to `customer_email`. COD orders are emailed when they are created; online orders only once paid.
- Without it, the form has "1. General Information" and a separate "Delivery Address" block.
- The Blanxer storefront shows Company Name and PAN/VAT together when `checkout.pan` is on.
- `checkout.extras.checkout_note`, when not empty, is shown under the total.
- The delivery place defaults to the first place in the table.

## "Checkout Powered by Blanxer"

The package's `Checkout` always renders this line under the place-order button:

```html
Checkout Powered by Blanxer
```

- It is part of the checkout (rule 2, owner decision 2026-10-11). There is no prop to remove it.
- Restyle it through `.bx-powered-by` and `.bx-powered-by a` (colour, size, font, spacing, alignment).
- Never remove, hide, cover or blend it into the background. Your own `footer` content goes below it.

## Delivery places and charges

`GET /public/delivery_charge/` returns:

```json
{
"defaults": [100, 150, 200, 250, 300, 400],
"places": [
["Kathmandu Inside Ring Road", true, 100, -1, -1, -1, -1, -1],
["Pokhara", "N", 150, 200, 250, 300, 350, 500],
["Ilam", "Y", -1, -1, -1, -1, -1, -1]
]
}
```

- `defaults` has 6 numbers, one per weight bracket.
- Each place is `[name, cod, ≤1 kg, ≤2 kg, ≤3 kg, ≤5 kg, ≤10 kg, >10 kg]`.
- `-1` in a place means "use the default for that bracket".
- A store that never saved a table gets 83 default places, all with COD on, all `-1`, and defaults of `0`: free delivery everywhere. The merchant edits the list in Blanxer (or you do, with the MCP and their confirmation).

### The rules

- **Weight** = the sum of `weight × quantity` over the ordered lines, in kg. The server uses the variant's weight for a variant line (0 when the variant has none) and the product's weight otherwise. The cart line falls back to the product's weight when the variant has none, so the preview can show a different delivery charge than the order.
- **Bracket index**: the first of `[1, 2, 3, 5, 10]` that the weight is `<=`; above 10 kg it is index 5.
- **Charge** = `place[index + 2]`; if that is below 0, `defaults[index]`.
- **COD is allowed for a place when `cod === true || cod === 'Y'`.** That is the server's rule. The Blanxer storefront uses `!!cod`, which treats `'N'` as yes; don't copy that.
- The place name must match exactly. An unknown place fails the order with `Selected delivery city not found, please try again`.

```ts
type DeliveryTable = { defaults: number[]; places: [string, boolean | string, ...number[]][] };

const BRACKETS = [1, 2, 3, 5, 10];

export function deliveryFor(table: DeliveryTable, place: string, weightKg: number) {
let i = BRACKETS.findIndex((max) => weightKg <= max);
if (i === -1) i = BRACKETS.length; // > 10 kg
const row = table.places.find((p) => p[0] === place);
if (!row) return { charge: 0, cod: false, known: false };
const n = (v: unknown) => (v === '' || v == null || isNaN(Number(v)) ? 0 : Number(v));
const own = n(row[i + 2]);
const cod = row[1] === true || row[1] === 'Y';
return { charge: own < 0 ? n(table.defaults[i]) : own, cod, known: true };
}
```

## Payment methods

The list is built from the store config. **Never add or remove a method by hand (rule 9).**

- **COD** is offered when the chosen place allows it (see above). It comes first.
- **Online methods** are offered only when `plan` is one of `basic`, `premium`, `plus`, `platinum`. On any other plan (free) the checkout is COD only.

In this order:

| `paymentMethod` | Offered when | Label in the Blanxer storefront | Flow |
|---|---|---|---|
| `COD` | The chosen place allows COD | Cash on delivery | No payment call |
| `QR_Dynamic` | `addons.fonepay_dynamic && setting.fonepay_dynamic_key` | Fonepay QR Payment | In-page QR |
| `FonepayCheckout` | `addons.fonepay_checkout && setting.fonepay_checkout_key` | Checkout by Fonepay | In-page QR + bank app links |
| `QR` | `addons.qr_request_enabled` | QR Payment | In-page QR (Blanxer QR) |
| `Esewa` | `addons.esewa && setting.esewa_secret` | Esewa | Form post to eSewa |
| `FonePay` | `addons.fonepay` | FonePay | Redirect |
| `Khalti` | `addons.khalti` | Khalti | Redirect |
| `NPX` | `addons.npx` | Nepal Payment Solution | Form post |
| `nbank_card` | `addons.nbank_card` | Visa/Mastercard | Redirect (Nabil Bank) |

- The payment-credential keys in `setting` arrive masked: `'yes'` when set, `''` when not (`fonepay_checkout_pubkey` is always `''`). Other `setting` keys come as stored. Test only the keys in this table, for truthiness.
- Card (Cybersource) is always off: `check_domain` always returns `addons.cybersource: false`.
- The strings are exact and case-sensitive. The server stores whatever string you send, so a typo creates an order no gateway will ever pay. A missing `paymentMethod` is saved as `COD`.
- The first available method is preselected. If the selected method disappears (for example COD after switching to a no-COD place), the package selects the first available one again. (The hosted storefront doesn't; it keeps the old selection and the server refuses it.)
- The server also saves the method as the customer's `preferred_payment_method`, for guests too.
- The server rejects COD for a place without COD: `Cash on delivery is not available for the selected delivery location`.

## Coupons

### Applying a code

```http
POST /public/coupon
Content-Type: application/json

{ "store": "", "code": "DASHAIN10",
"products": [{ "product": "", "variant": "", "quantity": 2 }] }
```

Response:

```json
{
"_id": "6705f0c2a1b2c3d4e5f60718",
"code": "DASHAIN10",
"coupon_type": 2,
"coupon_value": 10,
"min_order_value": 1000,
"max_discount_amount": 500,
"total_applicable_amount": 4200,
"only_for_cod_payment": false,
"only_for_online_payment": false,
"categories": [],
"places": []
}
```

- The code lookup is exact (case-sensitive). The package and the hosted storefront upper-case what the shopper types.
- The promo code box shows only when `store.plan` is set (not on the free plan).
- Errors are HTTP 400 `{message}`: `Coupan not found` (sic), `Coupon is inactive`, `All the available coupons have been used.`, `Coupon code not available` (not started yet), `Coupon code is expired`, `Cart must not be empty`, `Coupon is not applicable to any products` (category-restricted coupon, no matching product).
- **Each successful apply holds one use of the coupon for about 12 seconds.** That matters only for a coupon with a usage limit: on its last use, an order placed within ~12 seconds of Apply can fail with `All the available coupons have been used.` Call it when the shopper presses Apply, never on every keystroke.
- `total_applicable_amount` is the sum of `price × quantity` of the lines the coupon applies to (all lines, or only lines in the coupon's `categories`).

### Checks in the browser

The package re-checks the coupon on every change: payment method, place, delivery charge and cart total. (The hosted storefront re-checks when the coupon, delivery charge, payment method or place changes, but not when the cart total changes.) These give live feedback; the server enforces the same rules when the order is placed.

| Check | Message |
|---|---|
| `min_order_value !== -1 && subtotal + customization + delivery < min_order_value` | `Coupon is only applicable for order value above ` (`` formatted as currency, `en-IN`) |
| `only_for_cod_payment && paymentMethod !== 'COD'` | `Only cash on delivery can use this coupon` |
| `only_for_online_payment && paymentMethod === 'COD'` | `Only online payment method can use this coupon` |
| `places.length && place chosen && !places.includes(place)` | `This coupon is not valid for ` |

### The discount

```ts
// coupon_type: 1 = flat, 2 = percent, 3 = shipping (percent of the delivery charge)
export function couponDiscount(c: Coupon, deliveryCharge: number) {
const base = c.total_applicable_amount;
const max = c.max_discount_amount; // -1 = no cap
let d = 0;
if (c.coupon_type === 1) d = Math.min(base, c.coupon_value);
if (c.coupon_type === 2) {
const p = Math.floor((c.coupon_value / 100) * base);
d = max === -1 ? Math.min(p, base) : Math.min(p, max);
}
if (c.coupon_type === 3) {
const s = Math.floor((c.coupon_value / 100) * deliveryCharge);
d = max === -1 ? Math.min(s, deliveryCharge) : Math.min(s, max);
}
return Math.max(d, 0);
}
```

Total shown = subtotal + customization charges + delivery − discount (the discount only while the browser checks pass).

### Sending it with the order

- **Send the coupon's `_id` as `coupon`, never the code.** The server only looks at `coupon` when it is longer than 20 characters (an id is 24). A code like `DASHAIN10` is **silently ignored**: the order goes through with no discount and no error.
- Send `coupon: ''` when there is no coupon or a browser check fails.
- A `coupon` longer than 20 characters that isn't a valid id fails the order with HTTP 500.
- The server re-validates the coupon. If it fails, the whole order fails with one of: `Coupon not found` (spelled correctly here), `You are not allowed to perform this action` (another store's coupon), `This reward coupon belongs to another account`, `Coupon is inactive`, `All the available coupons have been used.`, `Coupon code not available`, `Coupon code is expired`, `Only cash on delivery can use this coupon`, `Only online payment method can use this coupon`, `This coupon is not valid for `, `Coupon is only applicable for order value above ` (the raw number, not formatted), `Coupon is not applicable to any products`.
- The server's discount is final. Its base includes customization charges when the coupon has no category restriction, so it can differ slightly from the preview.

### `?promo=`

Any page opened with `?promo=CODE` stores `CODE` in `localStorage['promo_code']` (`BlanxerProvider` does this). The checkout applies it once each time it opens with cart lines. The package also reads `?promo=` from the checkout URL itself. Use this for shared promo links.

- The stored code stays. It is applied again on later checkouts until another `?promo=` replaces it. (The hosted storefront clears it only on logout.)
- It is sent as stored, not upper-cased. Codes are case-sensitive, so `?promo=dashain10` gets `Coupan not found` for the code `DASHAIN10`. Write promo links with the code exactly as created.

## Custom fields

Some products ask the shopper for extra input (a name to engrave, a photo, a delivery time). The product detail response has them in `custom_fields`, as arrays:

```ts
// [type, label, required, placeholder, options, price]
type RawCustomField = [string, string, boolean, string, (string | { label: string; value: string })[]?, number?];
```

| Type | Input |
|---|---|
| `text` | Text |
| `text_dp` | Text with a price: when filled, `price` is added to the line's `customization_charge` |
| `textarea` | Long text |
| `image` | Image upload (below) |
| `date` | Date, minimum today |
| `time` | One of `8AM - 10AM`, `10AM - 12PM`, `12PM - 2PM`, `2PM - 4PM`, `4PM - 6PM`, `6PM - 8PM`, `8PM - 10PM` |
| `single` | One option (chips under 8 options, a select otherwise); the first option is preselected |
| `multi`, `checkbox` | Several options |

### Serialization

Each filled field becomes one string, `label|||type|||value`:

- arrays are joined with `, `;
- dates are formatted `MMM DD, YYYY` (for example `Oct 24, 2026`);
- an image is its uploaded URL.

```json
["Name on cake|||text|||Asha", "Delivery time|||time|||4PM - 6PM", "Photo|||image|||https://.../public_uploads/.../photo-1234.jpg"]
```

- A required field left empty shows `This field is required` and blocks Add to cart.
- Adding the same product and variant again goes into the existing line, even with different values (see [A cart line](#a-cart-line)).
- `customization_charge` is per unit. Send it on the line only when it is above 0, and send `custom_fields` only when at least one string is not empty.

### Image upload

```http
POST /product///file
Content-Type: multipart/form-data

file=
csrf_token=
```

- PNG, JPG, JPEG or WebP, else `Only png, jpg, jpeg, webp file is allowed!`. At most 5,900,000 bytes, else `You can only upload at max 5MB file`. No file: `File wasn't supplied.`
- Response: `{"success": true, "file": {"file_url": "https://...", ...}}`. Use `file.file_url` as the field's value.
- The file is stored as `public_uploads//_-<4 digits>`.
- The server does not currently check `csrf_token` or that the product exists; send the real values anyway.
- Upload from the browser.

## The order request

```http
POST /order/
Content-Type: application/json
```

```ts
interface OrderRequest {
products: {
product: string;
variant: string; // '' for a product without variants
quantity: number; // ≥ 1
customization_charge?: number; // per unit, only when > 0
custom_fields?: string[]; // only when at least one is not empty
print_id?: string; // the chosen print, for a print add-on product (see below)
}[];
meta?: { // Meta CAPI dedup, see "Meta events" below
event_id?: string; // ≤ 100
fbp?: string; // ≤ 200, the _fbp cookie
fbc?: string; // ≤ 400, the _fbc cookie
event_source_url?: string; // ≤ 1000, location.href
};
customer_full_name: string;
customer_phone_number: string;
customer_alt_phone_number: string; // '' when not given
customer_email: string; // '' when not given
customer_address_city: string; // the delivery place name
customer_address: string;
customer_address_landmark: string;
order_note: string;
sender_full_name?: string; // only with checkout.receiver_info
sender_phone_number?: string;
sender_email?: string;
delivery_date?: string; // YYYY-MM-DD, only with checkout.estimated_delivery
pan?: string;
company_name?: string;
paymentMethod: 'COD' | 'QR_Dynamic' | 'FonepayCheckout' | 'QR' | 'Esewa' | 'FonePay' | 'Khalti' | 'NPX' | 'nbank_card'; // missing = 'COD'
url: string; // window.location.origin
coupon: string; // coupon _id or ''
}
```

Example:

```json
{
"products": [
{ "product": "66f1c0ffee0000000000aa01", "variant": "66f1c0ffee0000000000bb07", "quantity": 1 },
{ "product": "66f1c0ffee0000000000aa02", "variant": "", "quantity": 2,
"customization_charge": 100, "custom_fields": ["Name on cake|||text_dp|||Asha"] }
],
"meta": { "event_id": "b6a3a0e2-1c1e-4f5e-9b8e-2f0c7d9e1a11", "fbp": "", "fbc": "",
"event_source_url": "https://mystore.com/checkout" },
"customer_full_name": "Asha Gurung",
"customer_phone_number": "9800000000",
"customer_alt_phone_number": "",
"customer_email": "asha@example.com",
"customer_address_city": "Pokhara",
"customer_address": "Lakeside, Ward 6",
"customer_address_landmark": "Near the boat station",
"order_note": "",
"paymentMethod": "Khalti",
"url": "https://mystore.com",
"coupon": "6705f0c2a1b2c3d4e5f60718"
}
```

The package sends no `Authorization` header (guest checkout). The hosted storefront sends a Bearer token for logged-in members, for loyalty; customer login is not part of BlanxerAPI.

### Print add-on products

A product can have a print add-on (`print_addon` on the product): the shopper picks a print, and the order line carries its id as `print_id`. When the add-on is on and required, a line without `print_id` fails with `Please choose a print for `; a print that is no longer allowed fails with `The selected print is no longer available for `. The list of prints comes from `GET /print-design/public/`, which isn't part of BlanxerAPI yet.

**The package has no print picker yet**, so it can't sell a product whose print is required. Before launch, check the store's products for `print_addon.enabled` and tell the merchant.

### What the server checks, in order

1. The body against the schema (lengths and formats above). Errors: HTTP 400 `{"error_type":"zod_validation","fields":{"":""}}`. Field keys are body keys, for example `customer_phone_number` or `products.0.quantity`. An empty `products` list: `Atleast a product is required`.
2. The testing short-circuit (see [Testing](#testing-without-creating-an-order)).
3. Email and sender email when the store requires them (HTTP 401, see the table above).
4. Lines with an empty `product` are dropped; if none is left: `Product is required`. Every product exists in this store and is `Active`, else `Either of the selected product is already deleted`.
5. A product with variants has a `variant`, else `Variant selection required for this product`; the print choice (see above); the variant exists, else `Either of the selected product has been modified, please add to cart again`.
6. Stock, unless the product has `continue_selling`: `Either of the selected product is out of stock`. Stores with advanced inventory are checked against the website outlet's stock.
7. Live flash sale limits: `Flash sale: you can buy at most N of "" per order.`
8. The stock hold. When the last units sit in other shoppers' checkouts: `The last units of an item in your cart are in other shoppers' checkouts right now. Please try again in about N minutes.`
9. The delivery place and COD (messages above).
10. The coupon (messages above).

Any other error is HTTP 400 `{"message": "..."}`.

**Rate limit:** more than 5 requests in 10 minutes for one store from one IP (the limiter keys on the store id and `cf-connecting-ip`) is HTTP 429 with the plain-text body `Too many requests, please try again later.` Every request counts, including test orders and failed ones. The limit runs before the test-phone check.

Prices are the server's: the variant's price if it has one, else the product's. The cart's prices are only shown. `customization_charge` and the custom-field values are taken from the request.

### The response

```json
{
"success": true,
"_id": "6709a1b2c3d4e5f607182930",
"order_number": 1042,
"total_price": 4180,
"total_quantity": 3,
"delivery_charge": 150,
"email": "asha@example.com",
"slug": "",
"hold_seconds": 300,
"hold_expires_at": "2026-10-11T09:15:00.000Z"
}
```

- `total_price` = products + customization charges − discount. **It does not include delivery.** The shopper pays `total_price + delivery_charge`.
- `hold_seconds` and `hold_expires_at` come only for online orders that hold stock.
- `slug` is always `''`.
- COD orders are created as `Pending`. Online orders are created as `Inactive` with `payment_status` `Unpaid`; it becomes `Processing` when a payment starts, and the order becomes `Pending` / `Paid` when the payment is confirmed.

Right after a successful response the component stores, in `sessionStorage`:

- `checkout_order_id` = `_id` (the success page needs it);
- `pixel_purchase_pending` = the Purchase event data, including the `event_id` sent in `meta`.

## Payment flows

Every payment start is a browser `POST` with the same body:

```json
{ "store": "", "order": "", "url": "https://mystore.com" }
```

The API checks the order belongs to the store, creates a payment transaction for `products + customization + delivery − discount`, and remembers `url` for the return.

- eSewa, Khalti, FonePay (and the unused card route) validate `url` with a strict URL check that **rejects `http://localhost:3000`**: HTTP 400 `{"fields":{"url":"Valid Return URL is required"}}`. Use `http://127.0.0.1:3000` locally, or test on the deployed site.
- QR, Checkout by Fonepay, NPX and Nabil card accept `localhost`. Their bad-URL error is `{"error_type":"zod_validation","fields":{"url":"Invalid url"}}`.
- If the gateway's verification fails, the API sets `payment_status` to `Failed`; the order stays `Inactive`.

### COD

No payment call.

1. Fire the browser Pixel `Purchase` with the stored `event_id` (no CAPI relay; the server already sent the CAPI Purchase for COD).
2. Remove the ordered lines from the cart and clear the two `sessionStorage` keys.
3. `router.replace('/track/<_id>?from=checkout')`.

### eSewa (form post)

`POST /payment/esewa/init` returns the eSewa v2 form:

```json
{
"action_url": "https://rc-epay.esewa.com.np/api/epay/main/v2/form",
"amount": 4330, "total_amount": 4330,
"product_service_charge": 0, "product_delivery_charge": 0, "tax_amount": 0,
"transaction_uuid": "6709a1b2c3d4e5f6071829aa",
"product_code": "EPAYTEST",
"success_url": "https://api.blanxer.com/payment/esewa/verify",
"failure_url": "https://api.blanxer.com/payment/esewa/verify",
"signed_field_names": "total_amount,transaction_uuid,product_code",
"signature": "..."
}
```

Build a hidden `` with one hidden input per key **except** `action_url`, append it to the body and submit it. eSewa returns to the API, which verifies the payment and redirects to `/payment/success` or `/payment/failed`.

- `product_code` `EPAYTEST` means the store is on eSewa's test environment, with the `rc-epay.esewa.com.np` form above. A live store gets `https://epay.esewa.com.np/api/epay/main/v2/form`.
- `success_url` and `failure_url` point at `api.blanxer.com` in production and at `api-dev.blanxer.com` elsewhere.
- **Known limitation (likely, not yet tested):** if the shopper cancels and eSewa returns without a valid `data` parameter, the API answers HTTP 400 JSON on its own host instead of redirecting to `/payment/failed`. The order stays `Inactive`.

### Khalti (redirect)

`POST /payment/khalti/init` returns Khalti's own initiate response, which includes `payment_url` (and `pidx`, `expires_at`, `expires_in`). Set `window.location.href = payment_url`. Khalti returns to the API (`/payment/khalti/verify/`), which redirects to success or failed. Khalti's error text is passed through as `{message}`; show it. It can read `[object Object]` when Khalti returns a structured error. Opening the verify link again for an order that is already paid returns HTTP 400 `{"message":"Payment already received"}` on the API host.

### FonePay (redirect)

`POST /payment/fonepay/init` returns `{"url": "https://..."}`. Set `window.location.href = url`.

### NPX, Nepal Payment Solution (form post)

`POST /payment/npx/init` returns `{ "action_url": "...", ...fields, "Signature": "..." }`. Post a hidden form exactly as for eSewa.

### Nabil card (redirect)

`POST /payment/nabil_card/init` returns `{"url": "https://..."}`. Redirect to it. A failed card payment returns to `/payment/failed?method=card`.

### Fonepay QR (`QR_Dynamic`) and Blanxer QR (`QR`)

```http
POST /payment/dynamic_qr/init
{ "store": "...", "order": "...", "url": "...", "self": true } // QR_Dynamic: the store's own Fonepay
{ "store": "...", "order": "...", "url": "..." } // QR: Blanxer QR (needs addons.qr_request === 'approved')
```

Response:

```json
{ "prn": "6709a1b2c3d4e5f6071829aaxkqz", "transaction": "6709a1b2c3d4e5f6071829aa",
"amount": 4330, "socket_url": "wss://...", "qr_message": "000201010212..." }
```

1. Open a modal. Render `qr_message` as a QR code and show `amount`.
2. Start the hold timer (see [Stock holds](#stock-holds)).
3. Every 5 seconds while the tab is visible, and right away when the shopper returns to the tab, call `GET /payment/dynamic_qr/check/`. HTTP 200 `{"success": true}` = paid. HTTP 400 `{"message":"Payment not received"}` = not yet. Payment confirmation itself happens on the server, from Fonepay's websocket.
4. A **Check Payment** button runs the same check and says `Payment has not been received yet.` when it isn't.
5. When paid: remove the ordered lines from the cart, close the modal, `router.push('/payment/success')`.

Blanxer QR on a store whose QR request isn't approved fails with `QR request is not approved for this store`.

### Checkout by Fonepay (`FonepayCheckout`)

`POST /payment/fonepay_checkout/init` returns the QR data plus a bank list:

```json
{
"prn": "6709a1b2c3d4e5f6071829aaxkqz", "transaction": "6709a1b2c3d4e5f6071829aa",
"amount": 4330, "socket_url": "wss://...", "qr_message": "000201010212...",
"banks": [{ "bankName": "...", "bankCode": "...", "bankIcon": "https://...", "packageName": "...", "intentScheme": "..." }]
}
```

- **Desktop:** show the QR, as above.
- **Mobile with banks:** show a searchable bank list. Tapping a bank opens `${intentScheme}/?qrPayload=${encodeURIComponent(qr_message)}`. If the page is still visible 2 seconds later, show "Mobile banking App not found". Offer "Scan QR Code Instead" and "Check Status".
- **Websocket:** open `socket_url`. Each message is JSON whose `transactionStatus` is itself a JSON string. When its `productNumber` equals `prn` and `paymentSuccess` is true, run the check below.
- **Check:** every 10 seconds while visible (this one asks Fonepay, so less often), on tab return, and on "Check Status": `GET /payment/fonepay_checkout/check/`. HTTP 200 `{"success": true, "amount": 4330}` = paid; HTTP 400 `{"message":"Payment not received"}` = not yet.
- When paid: same as the QR above.
- Outside production (`api-dev`), Checkout by Fonepay uses Fonepay's development credentials and charges 1.1, not the order amount. The `amount` in the response is still the order's real amount.

### Errors when starting a payment

If a start call fails, the component shows that method's error (for example "Khalti payment is not available at the moment, please try again later."; for Khalti, Khalti's own message when there is one) and stops. (The hosted storefront shows the eSewa text for an NPX failure.) The order already exists as `Inactive`; the merchant sees it in the dashboard and may call the shopper. For redirect gateways the ordered lines were already removed from the cart, so they are gone even when the start fails.

## Stock holds

- When an order is created, the API holds the units of every line whose product does **not** have `continue_selling`. Holds are atomic across all shoppers.
- **COD** reduces stock at once and ends the hold. **Online** orders keep the hold until paid, released or expired.
- **Hold time:** 300 seconds by default. If a product in the order is in a live flash sale, the sale's hold time applies (2–5 minutes, default 3); the shortest wins.
- `hold_seconds` is missing when nothing was held (every line continues selling) and for COD.

### The QR timer

- Timer = `hold_seconds − 20` seconds, so a payment made in the last seconds still lands inside the hold. If `hold_seconds` is missing or ≤ 20, the timer is 280 seconds.
- It is measured from when the QR opens, on the device clock.
- Show the time left as `MM:SS`. It turns red in the last 60 seconds.
- When it runs out, the modal shows "QR is expired" with **Back to checkout** and **Go to home**.

### Releasing a hold

```http
POST /order/public/release-hold
{ "store_id": "...", "order_id": "...", "transaction_id": "" }
```

Response: `{"success": true, "released": true}`, or `"released": false` when the order is already paid or no longer `Inactive`.

Release **only** when:

1. the timer runs out (then show "QR is expired" and "Your items were released so other shoppers can buy them. If you already paid, your order is still confirmed."), or
2. the shopper taps ✕ and confirms. While the QR is live, ✕ first asks "Cancel this payment?" with **Check payment** as the main button, then "Back to QR", then "Yes, cancel payment".

**Never** release on tab switch, page hide or page leave: shoppers pay in their banking app while the QR stays open. A payment that lands after a release is still honoured. The units were already released, so this can oversell (known). For redirect gateways the hold simply expires.

## When the cart is cleared

Only the selected lines are ordered and removed; unselected lines stay in the cart.

| Method | Ordered lines removed |
|---|---|
| COD | Right after the order is created |
| `Esewa`, `Khalti`, `FonePay`, `NPX`, `nbank_card` | Right after the order is created, before the redirect. A shopper who comes back from a failed payment finds those lines gone. |
| `QR`, `QR_Dynamic`, `FonepayCheckout` | Only when the payment is confirmed. Closing the QR keeps them, so the shopper can try again (which creates a new order). |

## The three required pages

These pages are not optional (rule 3):

- every redirect gateway returns the shopper to `/payment/success` or `/payment/failed`;
- the order confirmation email links to `/track/`;
- once the site link is saved in Blanxer, the tracking link Blanxer generates (dashboard copy, `get_tracking_link`) and the delivered email point at `/track/`. (Whether SMS short links follow it is not yet verified.)

If a page is missing, the shopper sees a 404 **after paying**. The package ships all three: `PaymentSuccess`, `PaymentFailed`, `OrderTracking`. Mark all three `noindex`.

### `/payment/success`

A client component, on the same origin as `/checkout` (it reads `sessionStorage`):

1. Read and remove `sessionStorage['checkout_order_id']`.
2. If `sessionStorage['pixel_purchase_pending']` exists, fire `Purchase` on the Pixel and the CAPI relay with its `event_id`, `email` and `phone`, then remove it.
3. `router.replace('/track/?from=checkout')`, or `/` when there is no id.

The gateway adds no order id to the URL. `sessionStorage` is the only link between the checkout and this page.

### `/payment/failed`

Show "Payment for your order failed" and "However, you might receive call/sms soon for confirmation", plus a "Shop More" link. With `?method=card`, show "Transaction Failed" and the card reasons: wrong card number, expiry or CVV; wrong OTP; the bank declined online transactions; try again. Don't say the order was cancelled: it exists as `Inactive`.

### `/track/[id]`

`GET /order/public//id/` returns:

| Field | Notes |
|---|---|
| `_id`, `slug`, `status`, `payment_status` | Status: `Inactive`, `Draft`, `Pending`, `Processing`, `Dispatched`, `Delivered`, `Cancelled`, `Returned`. Payment: `Unpaid`, `Processing`, `Paid`, `Failed`, `Refunded`. |
| `customer_full_name`, `customer_email`, `customer_address_city`, `customer_address`, `customer_address_landmark`, `customer_address_province` | |
| `customer_phone_number` | Masked: the first 7 digits become `•••••••` |
| `ordered_products[]` | `image_url`, `product_id`, `product_name`, `price`, `compare_at_price`, `variant_id`, `variant_name`, `quantity`, `print` |
| `product_total_price`, `delivery_charge`, `customization_total`, `discount` (the full object: `d_value`, `code`, ...), `partial_payment_amount` | Total = `product_total_price + delivery_charge + customization_total − discount.d_value` |
| `store` | The store id |
| `review` | `{count, total_rating, received: [product ids], reviews: [ids]}` |
| `reviews[]` | `product`, `images`, `review`, `rating` |

The response has no `order_number`. An unknown id is HTTP 400 `{"message":"Order item not found"}`; an id that isn't 24 hex characters is HTTP 400 `{"error_type":"zod_validation","fields":{"order_id":"..."}}`. The package shows "Order not found" for both. (The hosted storefront redirects to `/` on any error.)

What the page shows:

- With `?from=checkout`: "Congratulations! Your order has been placed successfully! Thank you for your purchase. You will receive a confirmation SMS or call soon."
- The status and payment status, the lines, and the totals. If `partial_payment_amount > 0`, show it and "Cash on Delivery: total − partial".
- **Cancel** when `status` is `Pending` or `Processing` and `checkout.extras.allow_customer_cancellation` is on. See [Forms and extras → Cancel an order](https://developers.blanxer.com/api-docs/forms-and-extras.md#cancel-an-order).
- **Review** per product when `status` is `Delivered` and the product isn't in `review.received`. See [Forms and extras → Review a product](https://developers.blanxer.com/api-docs/forms-and-extras.md#review-a-product).

## Meta events in the checkout

- `InitiateCheckout` once, when the checkout has lines: `content_ids` (a variant line is `_`, the same ids as the product feed), `content_type: 'product'`, `value` (the payable total), `currency: 'NPR'`, `num_items` (the number of unique content ids).
- `Purchase`: `num_items` is the number of order lines. One `event_id` per order, sent in the order's `meta` block. COD: the server sends the CAPI Purchase and the browser fires the Pixel. Online: the success page fires both. Meta dedupes on `event_id`.

Details: [SEO and tracking → Meta Pixel and Conversions API](https://developers.blanxer.com/api-docs/seo-and-tracking.md#meta-pixel-and-conversions-api).

## Testing without creating an order

On any store, an order with `customer_phone_number` `0000000000`, or a `customer_email` containing `mailinator.net`, returns `{"success": true}` and **creates nothing**.

- The body is validated first, so every other field must still be valid.
- The response has no `_id`. The checkout must treat `success` without `_id` as a test response and stop: no payment start, no redirect.
- It still counts toward the order rate limit (5 per 10 minutes per store and IP).
- This tests the form, validation, delivery and coupon display. It can't test payments: there is no order to pay, so the gateway and QR screens are checked live (see [Testing](https://developers.blanxer.com/api-docs/testing.md)).

## Not in v1

Partial payment, offers and agreed delivery are not in the package's checkout v1. They come in checkout v1.1. Neither is a print picker (see [Print add-on products](#print-add-on-products)). Customer login, loyalty discounts and reward points are not part of BlanxerAPI.

---

# Forms and extras

Custom forms, back-in-stock alerts, order cancellation, product reviews and the blog. Every write on this page is a browser call (rule 5), with no login.

## Forms

Merchants build forms in Blanxer (enquiries, bookings, wholesale requests). A custom site renders a published form at `/forms/`.

### Read a form

```http
GET /public/form//
```

```json
{
"form": {
"name": "Wholesale enquiry", "slug": "wholesale",
"page_header": "Work with us", "page_subheader": "...",
"title": "...", "description": "...",
"submit_label": "Submit", "success_message": "Thanks! We'll call you.",
"page_footer": "HTML",
"fields": [
{ "key": "full_name", "type": "text", "system": true, "label": "Full Name", "required": true, "width": "half" },
{ "key": "phone", "type": "text", "system": true, "label": "Phone Number", "required": true, "width": "half" },
{ "key": "email", "type": "text", "system": true, "label": "Email Address", "required": false, "width": "full" },
{ "key": "k8f2", "type": "select", "label": "Business type", "required": true, "options": ["Retail", "Online"] }
]
}
}
```

- Only `published` forms are returned. Anything else is HTTP 400 `{"message":"Form not found"}`; render a 404.
- Each field has `key`, `type`, `label`, `placeholder`, `help_text`, `required`, `width` (`full` or `half`), and for some types `options`, `multiple`, `sub_fields` (`{key, label, placeholder, icon}`), `min`, `max`, `step`.
- `page_footer` is HTML; sanitize it before rendering.
- Every form has the three system fields `full_name`, `phone` and `email`.

### Submit

```http
POST /public/form///submit
Content-Type: application/json

{ "data": { "full_name": "Asha Gurung", "phone": "9800000000", "email": "", "k8f2": "Retail" } }
```

The server also accepts the values as a flat body, without `data`. Send `data`.

Response: `{"success": true, "message": ""}`. Show the message.

Values are keyed by field `key` and checked against the published form:

| Type | Value | Rule |
|---|---|---|
| `full_name` (system) | string | 1–200 characters: `Full name is required` (`Required` when the key is missing) |
| `phone` (system) | string | Exactly 10 digits: `Phone number must be of 10 digit` |
| `email` (system) | string | Valid email; may be `''` unless required (then `Provided email address is invalid`) |
| `text`, and any type not listed | string | ≤ 1000 |
| `textarea` | string | ≤ 5000 |
| `richtext` | HTML string | ≤ 50000 |
| `select`, `radio` | string | One of `options` |
| `badges` | string, or string[] when `multiple` | From `options` |
| `checkbox_group` | string[] | From `options` |
| `tags` | string[] | ≤ 30 items, each ≤ 120 |
| `number`, `slider` | number | Within `min`/`max` (slider defaults to 0–100) |
| `email` | string | Valid email |
| `phone` | string | `/^\+?[\d\s-]{6,20}$/` |
| `url` | string | A full URL |
| `date` | `YYYY-MM-DD` | |
| `time` | `HH:MM` | |
| `datetime` | `YYYY-MM-DDTHH:MM` | |
| `color` | `#RRGGBB` | |
| `checkbox` | boolean | Required means it must be ticked |
| `multi_text` | `{ [sub_field.key]: string }` | Each ≤ 500 |
| `heading`, `divider` | — | Layout only; don't send |

- A required custom field that is empty fails with ` is required`.
- **Leave out choice fields the shopper didn't answer.** An optional `select`, `radio` or single `badges` field sent as `''` fails with `Invalid option for `.
- Errors: HTTP 400 `{"error_type":"zod_validation","fields":{"":""}}`. Show each message under its field.
- Unknown keys are dropped.
- An unknown or unpublished form: HTTP 400 `{"message":"Form not found"}`.
- Limit: 10 submissions per 15 minutes per IP.

The package's `BlanxerForm` component renders and submits a form; style it through its class hooks.

## Back-in-stock alerts

When a product (or the chosen variant) is out of stock and the store has `customer_program.back_in_stock.enabled`, show a "Notify me when available" form. Don't show it for `coming_soon` products.

```http
POST /customer/stock-alert
Content-Type: application/json

{ "store": "", "product": "", "variant_id": "",
"phone": "9800000000", "email": "asha@example.com",
"product_name": "Pashmina Shawl - Maroon/Large",
"product_url": "https://mystore.com/product/pashmina-shawl" }
```

- `phone` or `email` (or both) is required: `A phone number or email is required`. Check the phone is 10 digits in the browser.
- **Leave out a key that is empty.** `email: ""` fails with HTTP 400 `Invalid email`, even when `phone` is set.
- `product_name` and `product_url` go into the alert SMS/email as sent. Send the absolute product URL on the site (`https://mystore.com/product/`), without a query string.
- Response: `{"data": {"subscribed": true}, "message": "We'll notify you when it's back in stock."}`.
- If the store has the feature off: `This feature is not enabled for this store.` Other errors: `Store not found!`, `Product not found!`.
- Repeating the same request doesn't create a second alert.
- This is the only `/customer/*` route a custom site uses. It needs no login. Everything else under `/customer` is off limits (rule 7).

The package's `StockAlertForm` does this.

## Cancel an order

On `/track/`, offer **Cancel Order** when the order's `status` is `Pending` or `Processing` and the store has `checkout.extras.allow_customer_cancellation`.

```http
POST /order/public/cancel
{ "store_id": "", "order_id": "", "phone_number": "9800000000" }
```

- The shopper types the phone number used for the order. Show the placeholder `ending with ` from the masked number in the tracking response.
- Success: `{"success": true, "message": "Order cancelled successfully"}`. Reload the tracking data.
- A phone that isn't 10 characters: HTTP 400 `{"error_type":"zod_validation","fields":{"phone_number":"Phone number must be of 10 digit"}}`, before any other check.
- Wrong phone: HTTP **401** `{"fields":{"phone_number":"Provided phone number don't match with order phone number"}}`. The phone is checked before the status, so a wrong phone on a Delivered order is also 401.
- Other errors (HTTP 400 `{message}`): `Store not found`, `Order cancellation is not available`, `Order not found`, `Only orders in Pending or Processing status can be cancelled`.
- Cancelling puts the stock back and sends the store's cancellation SMS if it has one.
- Ask "Are you sure you want to cancel this order? This action cannot be undone." first.

## Review a product

On `/track/`, when the order's `status` is `Delivered`, offer **Review Product** for each product in the order that isn't in `review.received`. (The server doesn't check the status; the page does.)

```http
POST /order/public/submit-review
{ "store_id": "...", "order_id": "...", "product_id": "...",
"rating": 5, "review": "Lovely colour, fast delivery.", "phone_number": "9800000000" }
```

- `rating` is 1–5; send a whole number (the server doesn't enforce it). `review` is up to 1000 characters.
- `phone_number` must be 10 characters, else HTTP 400 `{"error_type":"zod_validation","fields":{"phone_number":"Phone number must be of 10 digit"}}`.
- Success: `{"success": true, "message": "Review recorded successfully", "rating": 5, "review": "..."}`.
- Wrong phone: HTTP **401** `{"fields":{"phone_number":"..."}}`.
- Other errors (HTTP 400 `{message}`): `Order item not found` (no such order, or another store's), `Product has already been reviewed`, `Provided product not found in the following order`, `Selected product not found`.
- The review is published as a verified purchase and counts in the product's `total_rating` / `review_count`.

The package's `OrderTracking` component includes both the cancel and review flows.

## Blog

If the store has published posts, add `/blogs` and `/blog/[slug]`. Blanxer's sitemap lists them only when posts exist.

### List

```http
GET /public/blog/?limit=12&cursor=&category=&tag=&author=&q=
GET /public/blog//category/
GET /public/blog//tag/
GET /public/blog//author/
```

The `category`, `tag` and `author` routes take the same query parameters as the list (`limit`, `cursor`, `tag`, `q`, `author`, `category`); the path value wins over the query.

```json
{
"items": [{ "_id": "...", "name": "How to care for pashmina", "slug": "pashmina-care",
"excerpt": "...", "featured_image": "https://...", "author": { },
"categories": ["care"], "tags": ["pashmina"], "reading_time": 4,
"view_count": 120, "published_at": "2026-09-01T06:00:00.000Z" }],
"next_cursor": "eyJwIjoi...", "has_more": true,
"all_categories": [{ "slug": "care", "name": "Care", "image": "" }]
}
```

- `limit` is clamped to 1–50, default 12. Pass `next_cursor` back as `cursor` for the next page.
- `q` matches the post name or excerpt (case-insensitive). `author` is the author's user id (`author.user`).
- `all_categories` lists every category with live posts, for filter chips. Blanxer's sitemap lists `/blogs?category=` for every blog category in `check_domain.blog_categories`, even empty ones, so support the query parameter and show an empty state.

### One post

```http
GET /public/blog//
```

Returns the post with `name`, `slug`, `excerpt`, `featured_image`, `author`, `categories`, `tags`, `reading_time`, `published_at`, `seo_title`, `seo_description`, `seo_image` (already filled from the title, excerpt and image when the merchant left them empty), `no_index`, `sections`, plus `related` (up to 3 posts), and `products`, `single_products` and `blogs` referenced by the post's sections. Unknown or unpublished: HTTP 400 `{"message":"Blog post not found"}`.

The body is in `sections`, in Blanxer's section format (the same section codes as the page builder). A custom site renders the text and image sections it understands and skips the rest. Look at a real post's `sections` for the store you are building before writing the renderer. If `no_index` is true, add `noindex` to the page.

---

# SEO and tracking

Blanxer builds the product feed and the catalog sitemap. The site passes the sitemap through, renders metadata and JSON-LD from Blanxer's SEO fields, and loads the tracking tags the merchant set in Blanxer. SEO **text** is changed in Blanxer through the MCP, never hardcoded in the site.

## Files Blanxer builds

| File | URL | Cache |
|---|---|---|
| Catalog sitemap | `https://api.blanxer.com/public/sitemap/.xml` | Data rebuilt at most daily, and after product, category, page or store-settings changes. Brand and blog changes don't trigger a rebuild, so they can take up to 24 hours |
| Product feed (RSS 2.0 + `g:` namespace) | `https://api.blanxer.com/public/product-feed/.xml` | Data rebuilt at most hourly |

Both send `Cache-Control: public, max-age=3600, stale-while-revalidate=86400`. An unknown store id is HTTP 404.

**Every link in them is absolute, on the store's site origin:**

1. the saved site link (`storefront_url`), if set;
2. else the verified Blanxer custom domain;
3. else `https://_{.blanxer.io`.

So **save the site link in Blanxer before you submit either file** (`blanxer_set_storefront_url`, see [Deploy](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#link-the-site-to-blanxer)). Before that, they point at the Blanxer-hosted site. The API uses a changed link on the next request, but HTTP caches (`max-age=3600` plus `stale-while-revalidate=86400`) and the site's own `/sitemap-catalog.xml` (cached 3600 s) can serve the old links for an hour or more.

### What the catalog sitemap lists

- `/`, `/products`, `/collections/new-arrivals`
- `/collections/` for every category
- `/product/` for every Active, non-POS product
- `/brand/` for every brand
- `/blogs`, `/blog/`, and `/blogs?category=` for every category in `check_domain.blog_categories` (even one with no posts), when the store has published, indexable posts
- page-builder pages `/p/` **only when no site link is saved**; a custom site has none

This is why the paths are fixed (rule 10). It does not list `/brands`, `/sale`, `/search`, `/forms/` or any page you add. Those go in the site's own sitemap.

### What the product feed contains

Only Active, non-POS products. One `` per product, or per variant for products with variants:

- `g:id`: the product `_id`, or `_` for a variant, with `g:item_group_id` = the product `_id`;
- `g:link`: `/product/`;
- `g:title`, `g:description`, `g:image_link` (+ up to 10 `g:additional_image_link`), `g:condition`, `g:availability` (`in stock` / `out of stock`);
- `g:brand`: the product's brand, else the store's brand name or name;
- `g:product_type`: only when the product has categories;
- `g:price` and `g:sale_price`: when `compare_at_price` is above the selling price, `g:price` is `compare_at_price` (the regular price) and `g:sale_price` is the selling price; otherwise `g:price` is the selling price and there is no `g:sale_price`;
- `g:quantity_to_sell_on_facebook`.

Items without an image or a price above 0 are left out (Meta rejects them). The `g:id` values are the same ids the site must send as Meta `content_ids` (see [Meta Pixel](#meta-pixel-and-conversions-api)).

**Don't build a feed or a catalog sitemap in the site** (rule 10).

## The site's sitemap and robots

| Route | Content |
|---|---|
| `/sitemap.xml` | A sitemap **index** listing `/sitemap-catalog.xml` and any sitemaps of the site's own pages |
| `/sitemap-catalog.xml` | Blanxer's catalog sitemap, passed through unchanged |
| `/sitemap-pages.xml` (optional, you add it) | The site's own extra pages: `/brands`, `/sale`, `/forms/`, about, contact |
| `/robots.txt` | Allow all, keep private pages out, point to `/sitemap.xml` |

Google wants a sitemap on the same host as the pages it lists. That's why the site serves the catalog sitemap on its own host instead of linking to `api.blanxer.com`.

```ts
// app/sitemap-catalog.xml/route.ts
import { catalogSitemapRoute } from '@blanxer-dev/storefront/next';
export const GET = catalogSitemapRoute(); // fetches /public/sitemap/.xml
```

```ts
// app/sitemap.xml/route.ts (don't hand-write the index)
import { sitemapIndexRoute } from '@blanxer-dev/storefront/next';
export const GET = sitemapIndexRoute({ extra: ['/sitemap-pages.xml'] }); // leave out `extra` until you add that file
```

```ts
// app/robots.txt/route.ts
import { robotsRoute } from '@blanxer-dev/storefront/next';
export const GET = robotsRoute();
```

`robotsRoute()` allows everything, disallows `/checkout`, `/cart`, `/payment/`, `/track/` and `/cdn-cgi/` (add more with `{ disallow: [...] }`), and ends with `Sitemap: /sitemap.xml`. (The Blanxer-hosted storefront disallows `/checkout` and `/cdn-cgi/`.)

The origin comes from `siteOrigin()`: `SITE_URL`, else the saved `storefront_url`, else the request host.

## Page metadata

Use Next.js `generateMetadata`. The package's `storeMetadata`, `productMetadata`, `categoryMetadata`, `brandMetadata` and `blogPostMetadata` build these from the API data, so the merchant's SEO work in Blanxer shows up on the site. Titles get the template ` | <store name>` from the home page's metadata.

| Page | `<title>` | Description | Share image (`og:image`) |
|---|---|---|---|
| Home | The landing page's `seo_title` (`getHomeSeo()`), else `brand_name` (or `name`) | Landing `seo_description`, else `description`, else `top_bar_text` | Landing `seo_image`, else `hero_images[0]`, else the logo |
| Product | `seo_title`, else the name | `seo_description`, else `description`, else the name | `seo_image`, else `image_urls[0]` |
| Category | `seo_title`, else the name | `seo_description`, else the store `description`, else "Shop <name> at <store>." | `seo_image`, else the category `image`, else `hero_images[0]` |
| Brand | The brand page's `seo_title`, else the brand name | The brand page's `seo_description`, else "Shop <brand> at <store>." | The brand page's `seo_image`, else the brand logo |
| Blog post | `seo_title` | `seo_description` | `seo_image` (all three already defaulted by the API) |

Where the Blanxer-hosted storefront differs: its product `<title>` is the name (`seo_title` only for `og:title`), its category description falls back to `top_bar_text`, and its brand title has no brand-name fallback (the package's fallback is an improvement).

- Home SEO comes from the store's landing page (`GET /public/landing/<store_id>`, read by `getHomeSeo()`). Only stores on a page-builder plan have one; otherwise the store name and description are used.
- The brand page's SEO fields come from `GET /brand/public/products/<store_id>/<slug>` as `brand.page.seo_title`, `seo_description`, `seo_image`.
- Every page: `og:site_name` = the store name, `og:type` (`website`, `product`, `article`), `twitter:card` = `summary_large_image`, and a canonical URL `<origin><path>` without query strings (except `/blogs?category=`).
- `noindex` on `/cart`, `/checkout`, `/payment/success`, `/payment/failed`, `/track/[id]`, `/search`, and blog posts with `no_index`.
- On stores without a landing page, confirm the home title and description (the store name and description) with the merchant.

To improve the text, use the MCP: `blanxer_audit_seo`, then `blanxer_update_product_status_seo`, `blanxer_bulk_update_products`, `blanxer_bulk_update_categories_seo`, `blanxer_update_brand`. Confirm bulk changes first (rule 13). See [MCP for your website](https://developers.blanxer.com/api-docs/mcp-for-website.md).

## JSON-LD

Add structured data with the package's `productJsonLd`, `organizationJsonLd` and `breadcrumbJsonLd`, in a `<script type="application/ld+json">`.

**Product** (product pages), from real data only:

- `@type: Product`, `@id: <url>#product`, `name`, `url`, `description` (`seo_description` or the name), `image` (all `image_urls`);
- `offers`: `@type: Offer`, `price` (first variant's price, else the product's), `priceCurrency: NPR`, `availability` (`InStock` when `continue_selling`, or any stock), `itemCondition: NewCondition`, `seller` = the store;
- `sku` and `gtin` (barcode) when present, `brand` when the product has one, `category` from the first matching category name;
- `aggregateRating` only when `review_count > 0`: `ratingValue` = `total_rating / review_count` (the average, 1–5), `reviewCount`. (The Blanxer storefront puts the raw sum in `ratingValue`; don't copy that.)
- `review` entries only for real reviews.

**Organization** (home): `name`, `url`, `logo`, and `sameAs` with the `social` links that are set.

**BreadcrumbList** (product, category, brand): Home → Category or Brand → Product.

Never add placeholder ratings, prices or reviews (rule 8).

## Search Console verification

1. The merchant adds the site in [Google Search Console](https://search.google.com/search-console) as a **URL-prefix** property (`https://mystore.com/`) and picks **HTML tag**. They copy the tag or just its `content` value.
2. You call `blanxer_set_site_verification { google_verification_code: "<the tag or the content value>" }` through the MCP. Blanxer stores it in the `meta_tags` plugin as `{n: "google-site-verification", c: "<code>"}`.
3. The site renders every `meta_tags` entry as `<meta name={n} content={c}>` on the home page. `verificationMetadata(store)` from the package returns it as Next.js `metadata.verification` / `metadata.other`.
4. Wait about a minute for the caches, check the tag is in the page source, then click **Verify**.
5. Submit `https://<site>/sitemap.xml` under **Sitemaps**.

A **Domain** property (verified with a DNS TXT record) works too: the merchant adds the TXT record in their own Cloudflare DNS. Then no meta tag is needed.

## Google Analytics, Tag Manager and Clarity

The ids come from `check_domain.plugins`, an array of `{name, details}`:

- `ga`: a GA4 id (`G-...`);
- `gtm`: a Tag Manager id (`GTM-...`);
- `clarity`: a Microsoft Clarity id.

Set or change GA/GTM with `blanxer_set_site_verification { ga_id }` or `{ gtm_id }`. The package's `<Pixel>` loads GA4, GTM, Clarity and the Meta Pixel from these plugins, each only when its id is present and after the page is interactive. Never hardcode an id in the site.

## Meta Pixel and Conversions API

- **Pixel:** when `plugins` has `fb_pixel`, load Meta's `fbevents.js` with that id and track `PageView` on every route change.
- **Conversions API relay:** when `plugins` has `meta_capi` (its `details` is just `true`; the access token stays on Blanxer's server), every event is also sent to Blanxer, which forwards it to Meta. The relay goes through Blanxer's domain, so ad blockers don't drop it.

The package's `Pixel` component and `trackEvent` do both.

### Events

| Event | When | `custom_data` |
|---|---|---|
| `ViewContent` | Product page opens | `content_ids: [product _id]`, `content_name`, `content_type: 'product'`, `value`, `currency: 'NPR'` |
| `AddToCart` | Add to cart | `content_ids: ['<product>_<variant>' or '<product>']`, `content_name`, `content_type`, `value`, `currency` |
| `InitiateCheckout` | Checkout opens with lines | `content_ids`, `content_type`, `value`, `currency`, `num_items` |
| `Purchase` | Order placed (COD) / paid (online) | `content_ids`, `content_type`, `value`, `currency`, `num_items` |

`content_ids` must match the feed's `g:id`: `<product_id>_<variant_id>` for a variant line, the product `_id` otherwise. Otherwise Meta's catalog ads can't match events to products.

### The relay call

```http
POST /public/meta-event/<store_id>
Content-Type: application/json

{ "event_name": "AddToCart", "event_id": "<uuid, the same one passed to fbq as eventID>",
"event_source_url": "https://mystore.com/product/pashmina-shawl",
"fbp": "<_fbp cookie>", "fbc": "<_fbc cookie>",
"custom_data": { "content_ids": ["..._..."], "content_type": "product", "value": 2500, "currency": "NPR" } }
```

- `event_name` is one of `ViewContent`, `AddToCart`, `InitiateCheckout`, `Purchase`. Add `email` and `phone` only for `Purchase`.
- `custom_data` keeps only `value`, `currency`, `content_type`, `content_ids` (≤ 200), `contents` and `num_items`. Other keys, such as `content_name`, are dropped by the relay (the browser Pixel still gets them).
- A valid event always gets `{"success": true}`: also when the store has no `meta_capi`, and when forwarding to Meta fails. A malformed body is HTTP 400 (validation error).
- Limit: 100 per minute per IP.
- Send it from the **browser** with `fetch(..., { keepalive: true })` and don't wait for it. Blanxer forwards the caller's IP and user agent to Meta, so a server-side call would report the Worker instead of the shopper.

### Purchase without double counting

- The checkout creates one `event_id` per order and sends it in the order's `meta` block with `fbp`, `fbc` and `event_source_url`.
- **COD:** Blanxer's server sends the CAPI `Purchase` when the order is created. The browser fires only the Pixel `Purchase`, with the same `event_id`.
- **Online payments:** `/payment/success` fires the Pixel and the relay with that `event_id`.
- Meta dedupes on `event_id`.

## Register the product feed

After the site link is saved:

- **Meta Commerce Manager:** Catalog → Data sources → Data feed → scheduled feed from URL `https://api.blanxer.com/public/product-feed/<store_id>.xml`, hourly or daily.
- **Google Merchant Center:** Products → Feeds → scheduled fetch of the same URL.

Meta's and Google's crawlers fetch the feed from `api.blanxer.com` directly. That hasn't been checked against Cloudflare's bot rules yet, so after adding it, check the feed fetched without errors (Commerce Manager / Merchant Center shows the fetch status).

`blanxer_get_store_context` returns the feed and sitemap URLs (`product_feed_url`, `sitemap_url`) only once a site link is saved. They arrive with the BlanxerAPI release of the MCP.

---



# Images and speed

Most shoppers in Nepal browse on mid-range phones over mobile data. Image weight is the main reason a store site is slow. Every BlanxerAPI site must pass these targets before it is deployed:

- **Lighthouse mobile ≥ 90** on the home page, a product page and `/checkout`;
- **LCP < 2.5 s**.

`npx blanxer-storefront check` measures them (see [Package](https://developers.blanxer.com/api-docs/package.md#cli)).

## Rule 11, in full

**Optimise every image before it goes into the site.**

- Use `npx blanxer-storefront images`:
- resize to the largest size shown ×2 (hero 2560 px, banner 1600, card 800);
- export AVIF + WebP at ~75 quality;
- strip EXIF and location data;
- use SVG for logos when available.
- Never commit originals.
- Load with `next/image`: each page's main (LCP) image gets `preload`, the rest load lazily with correct `sizes`.
- **Product photos go into Blanxer through the MCP, never into the site.**
- No autoplay video backgrounds or GIF banners unless the merchant insists after hearing the speed cost.
- Fonts go through `next/font`, at most 2 families.

## Size per slot

Export at twice the largest width the slot is shown at, so it stays sharp on high-density screens.

| Slot | Shown at (CSS px, widest) | Export width | `sizes` example |
|---|---|---|---|
| Hero, full-width banner | 1280 | **2560** | `100vw` |
| Banner, half-width promo, blog cover | 800 | **1600** | `(max-width: 768px) 100vw, 50vw` |
| Product card, category tile, brand tile | 400 | **800** | `(max-width: 768px) 50vw, 25vw` |
| Logo | — | **SVG** when there is one; else 2× the shown height | — |
| Share image (`og:image`) | — | 1200 × 630, WebP or JPEG | — |

Budget, enforced by the check command:

- no file in `public/` over **300 KB**;
- no file wider than **2560 px**;
- no JPEG or PNG where WebP or AVIF fits (PNG stays fine for a logo with no SVG);
- every image rendered through `next/image` with a width and height (or `fill` with `sizes`);
- each page's main (LCP) image marked with `preload` (or `loading="eager"` + `fetchPriority="high"`); the check warns when no image is marked.

## Optimising a merchant's images

The merchant sends a hero photo, banner art, a logo. Before any of it goes into the repo:

```bash
npx blanxer-storefront images ./incoming ./public/images
```

It resizes, writes AVIF and WebP next to each other, strips metadata (EXIF, GPS) and prints a size report. Show the merchant a before/after table, for example:

| Image | Original | AVIF | WebP |
|---|---|---|---|
| hero.jpg | 6.8 MB, 6000 px | 212 KB, 2560 px | 298 KB, 2560 px |
| banner-sale.png | 2.1 MB, 3200 px | 96 KB, 1600 px | 141 KB, 1600 px |

Delete the originals; never commit them (`./incoming` belongs in `.gitignore`). Options and defaults: see the package README.

## Loading images

```tsx
import Image from 'next/image';
import hero from '@/public/images/hero.avif';

export function Hero() {
return <Image src={hero} alt="New winter collection" preload sizes="100vw" placeholder="blur" />;
}
```

- **One main image per page, marked with `preload`**: the largest image above the fold (usually the LCP element). Next.js 16 deprecates `priority`; use `preload`, or `loading="eager"` with `fetchPriority="high"`. Everything else loads lazily, which is `next/image`'s default.
- Always give `sizes` for responsive images, or the browser downloads the widest file.
- Write real `alt` text. Product images: the product name (and variant).
- Keep the image config the starter ships with. It is set up for Cloudflare Workers.

## Product photos

Product photos live in Blanxer. `image_urls` and variant `image_url` are absolute URLs on Blanxer's storage, often uploaded straight from a phone camera at full size. Never download them into the site. Load them through the package's loader, which asks a resize service for the width `next/image` needs:

```tsx
import Image from 'next/image';
import { blanxerImageLoader } from '@blanxer-dev/storefront/next';

<Image
loader={blanxerImageLoader}
src={product.image_urls[0]}
alt={product.name}
width={800}
height={800}
sizes="(max-width: 768px) 50vw, 25vw"
/>
```

The Blanxer-hosted storefront uses `https://wsrv.nl/?w=<width>&url=<image>` for thumbnails today. The package's loader does the same by default (WebP output, quality 75). `NEXT_PUBLIC_BLANXER_IMAGE_LOADER` switches it: `wsrv` (default), `cloudflare` (Cloudflare Image Transformations on the site's own zone, `/cdn-cgi/image/...`; the merchant must turn Transformations on in Cloudflare) or `none`. The loader hides the choice, so site code doesn't change. Local files and SVGs are passed through unchanged (they are already optimised).

To use it for every `next/image`, set it once in `next.config.ts`. If the starter already sets an image loader, keep the starter's setting:

```ts
// next.config.ts
const nextConfig = { images: { loader: 'custom', loaderFile: './src/lib/image-loader.ts' } };
export default nextConfig;

// src/lib/image-loader.ts
export { default } from '@blanxer-dev/storefront/image-loader';
```

New or better product photos go **into Blanxer through the MCP** (`blanxer_upload_product_image`, `blanxer_request_image_upload`), so the dashboard, POS, app, feed and site all get them. See [MCP for your website](https://developers.blanxer.com/api-docs/mcp-for-website.md).

## Video and GIFs

- No autoplay video backgrounds and no GIF banners by default. A 10-second background video is often heavier than the rest of the page together.
- If the merchant insists after hearing the cost, use a short, muted MP4/WebM with a `poster` image, `preload="none"`, no autoplay on mobile, and keep the poster as the LCP image.
- An animated banner is better as an AVIF/WebP sequence or CSS animation than a GIF.

## Fonts

- Load fonts with `next/font` (`next/font/google` or `next/font/local`). It self-hosts them and avoids layout shift.
- At most **2 families**. The store's font (`customization.font`, default Poppins) is usually one of them.
- Load only the weights you use, with `display: 'swap'`.
- If the site shows Nepali text, pick a family with a `devanagari` subset (for example Mukta or Noto Sans Devanagari) and include that subset. It still counts toward the 2.

## Other speed rules

- Read store and catalog data in **server components** (`@blanxer-dev/storefront/server`), not with client-side fetches above the fold.
- Keep client components small: cart, variant picker, checkout. Don't make whole pages client components.
- Load third-party tags (GA, GTM, Pixel, Clarity, chat widgets) with `next/script` `strategy="afterInteractive"` or `lazyOnload`.
- Avoid heavy UI and animation libraries for things CSS can do. They also count toward the Worker size limit (see [Deploy](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#worker-size)).
- Don't render page-builder data or embed the Blanxer-hosted site.

## When the check fails

| Failure | Fix |
|---|---|
| A file in `public/` is over 300 KB | Re-run `blanxer-storefront images` with the slot's export width; lower quality to ~65 for photos |
| A file is wider than 2560 px | It was committed unresized. Resize it. |
| JPEG/PNG found | Convert to AVIF + WebP |
| Image without width/height or `sizes` | Add them, or use `fill` + `sizes` |
| No image marked as main (warning) / the wrong one | Put `preload` on the LCP image only |
| LCP over 2.5 s | Usually the hero: check its size, `preload`, and that nothing (a font, a client fetch, a carousel script) delays it |
| Lighthouse under 90 | Read the report's top items; most often images, unused JavaScript or a third-party script loaded too early |

---



# The @blanxer-dev/storefront package

> This page summarises the package's API: entry points, functions, components and the CLI. The package README and its TypeScript types have every argument and return type. The package is at version 0.1.0 and not yet published to npm.

`@blanxer-dev/storefront` is the typed client, checkout and tooling every BlanxerAPI site uses. The starter already depends on it. Keep it (rule 2): the checkout, delivery, coupon, payment and tracking behaviour in it is copied from Blanxer's own storefront and covered by tests, and it is updated when Blanxer's checkout changes.

```bash
npm install @blanxer-dev/storefront
```

Peer dependencies: `next` ≥ 16 (App Router), `react` and `react-dom` ≥ 19. Node ≥ 20.9. ESM with TypeScript types.

## Environment

| Variable | Required | Default | Meaning |
|---|---|---|---|
| `BLANXER_STORE` | Yes | — | The store's subdomain (`mystore` in `mystore.blanxer.io`) or its custom domain, resolved with `check_domain` |
| `BLANXER_API` | No | `https://api.blanxer.com` | `https://api-dev.blanxer.com` for sandbox testing |
| `SITE_URL` | No | The saved `storefront_url` | The site's public origin, for canonical links, `robots.txt` and the sitemap index |
| `NEXT_PUBLIC_BLANXER_IMAGE_LOADER` | No | `wsrv` | Product photo resizing: `wsrv`, `cloudflare` or `none` |

No key, token or secret is ever needed (rule 6).

## Entry points

| Import | Runs on | For |
|---|---|---|
| `@blanxer-dev/storefront/server` | Server only | Reading store and catalog data |
| `@blanxer-dev/storefront/client` | Browser only | Orders, coupons, payments, holds, tracking, forms, events |
| `@blanxer-dev/storefront/react` | Browser (client components) | Provider, cart, product, checkout, the three required pages, forms |
| `@blanxer-dev/storefront/seo` | Server | Metadata and JSON-LD |
| `@blanxer-dev/storefront/next` | Server | Route handlers and the image loader |
| `@blanxer-dev/storefront/core` | Both | The pure logic: delivery, COD rule, coupons, payment method list, order payload, custom fields, validation, variants, formatting, types |
| `@blanxer-dev/storefront/image-loader` | — | The default image loader as a default export, for `loaderFile` |
| `@blanxer-dev/storefront/styles.css` | — | Default styles for the `bx-*` classes (optional) |
| `blanxer-storefront` (CLI) | Your terminal | `check` and `images` |

## `@blanxer-dev/storefront/server`

Server-only data functions. Each uses `fetch` with `next: { revalidate: 60 }` and a normal browser `User-Agent`. Responses are also kept in memory per server process / Worker instance for the same 60 seconds, so a Worker without an incremental cache still reads the catalog about once a minute, not once per page view. `opts` is `{ revalidate?: number | false }`.

| Function | Returns |
|---|---|
| `getStore(opts?)` | The full store config from `check_domain`. Server only: it contains plugin data |
| `getClientStore(opts?)` / `toClientStore(store)` | The browser-safe subset (no gateway keys or third-party plugin tokens), for `<BlanxerProvider store>` |
| `getStoreId()` | The store's `_id` |
| `getProducts(opts?)` | Every active product, unpaginated (prefer `getProductsPage`) |
| `getProductsPage({ page, perPage, sortBy, sortOrder }, opts?)` | `{ meta, products }`; `perPage` ≤ 100 |
| `getProduct(slug)` | The product, or `null` when it is missing, not Active or POS-only |
| `getCategory(slug)` | `{ category, storeCategory, products }` or `null`; `new-arrivals` included |
| `getBrands()` / `getBrand(slug)` | The brands / `{ brand, page, products }` or `null` |
| `searchProducts(q)` | Products (`[]` under 3 characters) |
| `getSaleProducts()` | Products on sale |
| `getDeliveryCharges()` | `{ defaults, places }` |
| `getFlashSales(opts?)` | `{ server_time, sales }` (not cached by default) |
| `getBlogPosts({ cursor, category, tag, author, q })` / `getBlogPost(slug)` | `{ items, next_cursor, has_more, all_categories }` / the post or `null` |
| `getForm(slug)` | The form or `null` |
| `getHomeSeo()` | `{ seo_title, seo_description, seo_image }` from the store's landing page (empty on stores without one) |
| `siteOrigin({ fromRequest? })` | The site's public origin: `SITE_URL`, else the saved `storefront_url`, else the request host. `{ fromRequest: false }` returns `''` instead of reading the request, which keeps a page static |
| `apiBase()`, `storeHandle()`, `blanxerGet(path, opts?)` | Low-level helpers |

Pass `getClientStore()` (or `toClientStore(store)`), not the raw `getStore()` result, to client components.

```tsx
// app/product/[slug]/page.tsx
import { notFound } from 'next/navigation';
import { getProduct } from '@blanxer-dev/storefront/server';

export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
const { slug } = await params;
const product = await getProduct(slug); // null for missing, non-Active and POS-only products
if (!product) notFound();
return <h1>{product.name}</h1>;
}
```

See [Catalog](https://developers.blanxer.com/api-docs/catalog.md) for what the product endpoints return.

## `@blanxer-dev/storefront/client`

Browser calls. This entry point imports `client-only`, so importing it from a Server Component, route handler or server action fails the build (rule 5).

| Function | Calls |
|---|---|
| `placeOrder(storeId, payload)` | `POST /order/:store_id` |
| `applyCoupon({ store, code, products })` | `POST /public/coupon` |
| `startPayment(method, { store, order, url? })` | The method's `/payment/*/init`. Returns the next step: `none`, `redirect`, `form`, `qr` or `fonepay_checkout` |
| `followPayment(start)` | Performs that step: navigates, or posts the eSewa/NPX form |
| `checkPayment('qr' \| 'fonepay_checkout', transaction)` | `GET /payment/dynamic_qr/check/:transaction` or `/payment/fonepay_checkout/check/:transaction` → `boolean` |
| `releaseHold({ store_id, order_id, transaction_id })` | `POST /order/public/release-hold` |
| `getOrder(storeId, orderId)` | `GET /order/public/:store_id/id/:order_id` |
| `cancelOrder({ store_id, order_id, phone_number })` | `POST /order/public/cancel` |
| `submitReview({ store_id, product_id, order_id, rating, review, phone_number })` | `POST /order/public/submit-review` |
| `requestStockAlert({ store, product, variant_id?, phone?, email?, product_name?, product_url? })` | `POST /customer/stock-alert` |
| `submitForm(storeId, slug, data)` | `POST /public/form/:store_id/:slug/submit` |
| `trackEvent(event, customData?, { eventId?, email?, phone? })` | Meta Pixel + `POST /public/meta-event/:store_id`, with one event id |

Also: `getDeliveryCharges`, `getFlashSaleForProduct`, `notifyFlashSale`, `uploadCustomFieldImage`, `pingAnalytics`, `pixelTrack`, `getEventId`, `buildOrderMeta`, `initMetaCapi`, `configureClient`, `BlanxerApiError`, `errorMessage`, `fieldError`.

`url` on orders and payments is always the site's own origin (`window.location.origin`). You rarely call these yourself: the React components do.

## `@blanxer-dev/storefront/react`

Client components and hooks. **Unstyled by default**: each element has a `bx-*` class, and the styles read CSS variables. The behaviour is fixed; style it, don't fork it.

| Export | What it is |
|---|---|
| `<BlanxerProvider store apiBase? theme? notify?>` | Wrap the app. Gives components the store config, holds the cart, remembers `?promo=`, sends the session ping, switches the Meta CAPI relay, sets the theme variables, shows toasts |
| `useBlanxer()` / `useStore()` | `{ store, storeId, apiBase, notify }` / the store |
| `CartProvider`, `useCart()` | The cart in `localStorage['cart_items']`, with line selection (`cart_selection`) |
| `<CartLines>`, `<CartView>` | Cart lines (optionally selectable and editable) and a full cart page |
| `<AddToCart product>` | Builds the cart line (variant `_id`, weight, custom fields, customization charge). Options to show the price, variants, custom fields, quantity, flash sale and stock alert |
| `useProductSelection(product)`, `<VariantPicker>`, `<CustomFields>`, `<QuantityPicker>` | Build your own product form from the same selection state |
| `<FlashSaleStrip productId>` | Countdown, units left, per-order limit, notify me |
| `<Checkout>` | The whole checkout: form, place select, delivery charge, coupons, payment methods, every gateway, QR modals with the hold timer. See [Checkout](https://developers.blanxer.com/api-docs/checkout.md). |
| `<PaymentSuccess>` | `/payment/success` |
| `<PaymentFailed method?>` | `/payment/failed` |
| `<OrderTracking orderId fromCheckout?>` | `/track/[id]`, with cancel and review |
| `<BlanxerForm form>` | A Blanxer custom form (from `getForm()`) |
| `<StockAlertForm product variantId?>` | Back-in-stock "Notify me" (alias `BackInStockForm`) |
| `<Pixel>` | Meta Pixel, GA4, GTM and Clarity from the store's plugins |
| `<Money amount>`, `useMoney()`, `<BlanxerImage>` | Prices with the store's currency label; `next/image` with the Blanxer loader |

### Theming

`BlanxerProvider` takes a `theme` prop. Each key sets a CSS variable that the `bx-*` styles read. `primary` defaults to the store's theme colour from Blanxer; the `theme` prop wins over it.

| `theme` key | CSS variable |
|---|---|
| `primary` | `--bx-primary` |
| `primaryContrast` | `--bx-primary-contrast` |
| `background` | `--bx-bg` |
| `foreground` | `--bx-fg` |
| `muted` | `--bx-muted` |
| `border` | `--bx-border` |
| `danger` | `--bx-danger` |
| `success` | `--bx-success` |
| `radius` | `--bx-radius` |
| `fontFamily` | `--bx-font` |

Two more variables have no `theme` key: `--bx-surface` (card and panel background) and `--bx-gap` (spacing). Set any of them in your own CSS, or target the `bx-*` classes directly.

```tsx
// app/layout.tsx
import { getClientStore, apiBase } from '@blanxer-dev/storefront/server';
import { BlanxerProvider, Pixel } from '@blanxer-dev/storefront/react';
import '@blanxer-dev/storefront/styles.css';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
const store = await getClientStore();
return (
<html lang="en">
<body>
<BlanxerProvider store={store} apiBase={apiBase()} theme={{ primary: '#0f766e', radius: '10px' }}>
{children}
<Pixel />
</BlanxerProvider>
</body>
</html>
);
}
```

```tsx
// app/checkout/page.tsx
import { getDeliveryCharges } from '@blanxer-dev/storefront/server';
import { Checkout } from '@blanxer-dev/storefront/react';
import { noIndexMetadata } from '@blanxer-dev/storefront/seo';

export const metadata = noIndexMetadata('Checkout');

export default async function CheckoutPage() {
const delivery = await getDeliveryCharges();
return <Checkout delivery={delivery} />;
}
```

`Checkout` also takes `labels` (button and section text), `className`, `header` and `footer` (your own content above the form and under the place-order area), `paymentMethodIcons` and `onOrderPlaced(order, method)`. Without `delivery`, it fetches the delivery table in the browser.

```tsx
// app/payment/success/page.tsx (likewise PaymentFailed and OrderTracking)
import { PaymentSuccess } from '@blanxer-dev/storefront/react';
import { noIndexMetadata } from '@blanxer-dev/storefront/seo';
export const metadata = noIndexMetadata('Payment');
export default function Page() {
return <PaymentSuccess />;
}
```

### "Checkout Powered by Blanxer"

`Checkout` always renders this under the place-order button:

```html
<p class="bx-powered-by">Checkout Powered by <a href="https://blanxer.com" target="_blank" rel="noopener noreferrer">Blanxer</a></p>
```

- Restyle it through `.bx-powered-by` (and `.bx-powered-by a`): colour, size, font, alignment, spacing.
- **Never remove or hide it** (rule 2). There is no prop to turn it off. Don't hide it with CSS (`display: none`, `visibility: hidden`, zero size, off-screen, same colour as the background) and don't cover it.
- Your own `footer` content renders below it.

### Where the package differs from the hosted storefront

- Test contacts (phone `0000000000` or a `mailinator.net` email) get `{ success: true }` with no order. The hosted storefront then goes to `/track/undefined`; `Checkout` shows "Test order accepted" and keeps the cart.
- Not ported on purpose: the customer login gate, loyalty tier discount and points preview (custom sites have no login), store-specific variants, and Card (Cybersource), which stays off.
- `Checkout` offers the optional delivery date from today only, like storefront `main`; the newer backend delivery-date rules aren't on `main` either.
- Payment methods are shown by name; logos are opt-in through `paymentMethodIcons`.
- The package re-selects a payment method that disappears, re-checks the coupon when the cart total changes, and shows per-method payment-start errors. See [Checkout](https://developers.blanxer.com/api-docs/checkout.md).

## `@blanxer-dev/storefront/seo`

| Export | Returns |
|---|---|
| `storeMetadata(store, { origin?, homeSeo? })` | Home `Metadata` (pass `homeSeo` from `getHomeSeo()`) |
| `productMetadata(product, store, { origin? })` | Product `Metadata` |
| `categoryMetadata(store, category, { origin? })` | Category `Metadata` |
| `brandMetadata(store, brand, page?, { origin? })` | Brand `Metadata` |
| `blogPostMetadata(post, store, { origin? })` | Blog post `Metadata` |
| `noIndexMetadata(title)` | `noindex` metadata for cart, checkout, payment and tracking pages |
| `verificationMetadata(store)` | Search Console and other `meta_tags` from the store's plugins |
| `productJsonLd`, `organizationJsonLd`, `breadcrumbJsonLd` | schema.org `Product`, `Organization`, `BreadcrumbList` |
| `jsonLd(data)` | A safe serialiser for `<script type="application/ld+json">` |

Canonical URLs are only emitted when the origin is known. What they produce: [SEO and tracking](https://developers.blanxer.com/api-docs/seo-and-tracking.md).

### Site tags (0.1.1+)

`storeMetadata` adds two tags to every page: `<meta name="generator" content="Blanxer Storefront">` and `<meta name="blanxer-store" content="<store id>">`.

- **What they're for:** Blanxer's nightly check reads them to confirm that the website link saved for a store is that store's own site. A site that answers but lacks them stays "linked", not "live", in Blanxer's records.
- **Keep them:** keep `storeMetadata` in the root layout.

## `@blanxer-dev/storefront/next`

| Export | Use |
|---|---|
| `sitemapIndexRoute({ extra? })` | `export const GET = sitemapIndexRoute()` in `app/sitemap.xml/route.ts`: an index of `/sitemap-catalog.xml` plus your own extra sitemaps |
| `catalogSitemapRoute()` | `export const GET = catalogSitemapRoute()` in `app/sitemap-catalog.xml/route.ts`. Proxies `/public/sitemap/:store_id.xml`. |
| `robotsRoute({ disallow? })` | `export const GET = robotsRoute()` in `app/robots.txt/route.ts` |
| `blanxerImageLoader`, `createImageLoader(provider)` | `next/image` loader for product photos (asks a resize service for the width needed) |

## CLI

```bash
npx blanxer-storefront check [dir] [--lighthouse <origin>] [--offline] [--no-worker-size] [--json]
npx blanxer-storefront images <in> <out> [--max-width 2560] [--quality 75] [--formats avif,webp]
```

### `check`

Run before every deploy. It prints a PASS/FAIL table and fails when:

- `BLANXER_STORE` isn't set, or Next.js or the package is missing;
- a contract route is missing: `/`, `/products`, `/product/[slug]`, `/collections/[slug]`, `/brand/[slug]`, `/brands`, `/search`, `/sale`, `/cart`, `/checkout`, `/payment/success`, `/payment/failed`, `/track/[id]`, `/forms/[slug]`, `/blogs`, `/blog/[slug]`, `/sitemap.xml`, `/sitemap-catalog.xml`, `/robots.txt`; or `/checkout` doesn't render the package's `<Checkout>`;
- there are account, login, wishlist, rewards or `/p/` pages, or calls to `/customer/auth`, `/customer/account`, wishlist or rewards;
- a secret is in the code, env files, `wrangler` config or the build output (`sk_` keys, gateway keys, plugin tokens, passwords, JWTs);
- `@blanxer-dev/storefront/client` is imported by server files, or the code calls payment, coupon or hold endpoints directly;
- the image budget is broken: see [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md#size-per-slot). It also warns when no image on a page is marked as the main (LCP) image;
- with `--lighthouse <origin>` (the production build running with `next start`): Lighthouse mobile is under 90 or LCP over 2.5 s on the home page, one product page and `/checkout`. It runs `npx --yes lighthouse` and needs Chrome.

It also lists the store's delivery places and payment methods. `--offline` skips the network checks. After an OpenNext build it reports the Worker size against the 3 MiB free-plan limit.

### `images`

Resizes images (never enlarges; default max width 2560, `--max-width` to change it), writes AVIF and WebP (~75 quality; `--quality`, `--formats`), copies SVGs, strips EXIF and location data, and prints a before/after size report. Needs `sharp` (an optional dependency of the package). See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md#optimising-a-merchants-images).

## Versions

The checkout is versioned: checkout v1 matches Blanxer's storefront `main` at `cabd695` (stock holds and flash sales included). Partial payment, offers and agreed delivery come in checkout v1.1. Update the package to get checkout fixes; the site code doesn't change.

---



# MCP for your website

The site's code only **reads** Blanxer, through the public API. Everything you **change** in the store while building (SEO text, products, photos, categories, coupons, delivery charges, the site link) you change through the Blanxer MCP, in your chat with the merchant. The site never holds a key and never calls the MCP (rule 6).

## Connect

The server is `https://mcp.blanxer.com/mcp` (streamable HTTP). The merchant signs in to Blanxer in the browser (OAuth). You never see a password or key, and you never ask for one.

**Claude Code**

```bash
claude mcp add --transport http blanxer https://mcp.blanxer.com/mcp
```

Or install the skill, which brings the MCP with it:

```
/plugin marketplace add blanxer-dev/blanxer-agent-skills
/plugin install blanxer-website@blanxer
```

Then run `/mcp`, pick `blanxer` and sign in.

**Cursor**: add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "blanxer": { "url": "https://mcp.blanxer.com/mcp" } } }
```

**Codex**: add to `~/.codex/config.toml`:

```toml
[mcp_servers.blanxer]
url = "https://mcp.blanxer.com/mcp"
```

Sign in when Codex asks (recent versions: `codex mcp login blanxer`).

**claude.ai**: Settings → Connectors → Add custom connector → URL `https://mcp.blanxer.com/mcp`.

The tools act as the person who signed in, with their role in the store. Most writes need the **owner** or a **manager**. If a tool says the role isn't allowed, ask the merchant to sign in as the owner.

## What you use it for

| While building the site you… | MCP tool | The site reads it from |
|---|---|---|
| Find SEO gaps | `blanxer_audit_seo` | — |
| Write product titles and descriptions for search | `blanxer_update_product_status_seo`, `blanxer_bulk_update_products` | Product `seo_*` → page metadata |
| Write category and brand SEO | `blanxer_bulk_update_categories_seo`, `blanxer_update_category`, `blanxer_update_brand` (brand SEO is saved only when the brand has a page; `''` can't clear a field) | `check_domain.categories`, brand details |
| Verify Search Console, add GA / GTM | `blanxer_set_site_verification` | `check_domain.plugins` → the package renders the tags |
| Add products and photos | `blanxer_create_product`, `blanxer_bulk_create_products`, `blanxer_bulk_import_products`, `blanxer_upload_product_image`, `blanxer_request_image_upload` | Product endpoints |
| Create categories and brands for the menus | `blanxer_create_category`, `blanxer_create_brand`, `blanxer_reorder_categories` | Categories / brands |
| Set up launch coupons | `blanxer_create_coupon` | `/public/coupon` |
| Fix delivery places, charges and COD | `blanxer_get_delivery_charges`, `blanxer_update_delivery_charges` | `/public/delivery_charge` |
| Change the store name or description (shared with the Blanxer site) | `blanxer_update_store_profile` (only the top-level `name` and `description`) | `check_domain.name`, `description` |
| Change logo, favicon, brand name or colours (shared with the Blanxer site and emails) | `blanxer_update_appearance` | `check_domain.customization` |
| Write blog posts | `blanxer_create_blog_post` (an empty post), then its body with `blanxer_add_section` / `blanxer_update_section` using `{ post_id }`, then `blanxer_set_blog_post_status` | `/public/blog/*` |
| **Save the website link** | **`blanxer_set_storefront_url`** (new): preview, then `{ dry_run: false, confirm_token }` | — |
| Get the feed and sitemap URLs | `blanxer_get_store_context` (only once a website link is saved) | — |
| Retire the subdomain site | `blanxer_update_appearance { store_visibility: 'hidden_on_subdomain' }` | — |

`blanxer_how_to` returns step-by-step guides for store tasks (SEO pass, editing products, and more). For the whole custom-site flow: `blanxer_how_to { operation: 'custom_website' }`.

With a website link saved, `blanxer_audit_seo` treats the custom site as the live site and reports `<site>/sitemap.xml` as the sitemap to submit.

### `blanxer_set_storefront_url`

```
blanxer_set_storefront_url { url: "https://mystore.com" } // preview a save or change
blanxer_set_storefront_url { url: null } // preview clearing it
blanxer_set_storefront_url { dry_run: false, confirm_token: "..." } // apply, after the merchant's yes
```

- Owner or manager.
- **The first call saves nothing.** It shows the old and the new value and returns a `confirm_token`. Show the merchant the change; after their yes, call again with `{ dry_run: false, confirm_token }` only. If the link changed since the preview, the apply is refused; preview again.
- Blanxer cleans the link to `https://<host>`: it must be `https`, with no path, query, port or login, and not an IP or `localhost`. A bare `mystore.com` becomes `https://mystore.com`. A `*.workers.dev` link is fine. The MCP refuses `*.blanxer.io` and `*.blanxer.com` addresses (those are the Blanxer-hosted site).
- A save returns the product feed URL, the sitemap URL, and a reminder about the subdomain switch. Clearing returns only a confirmation (and a warning if the subdomain site is still hidden).

Once saved, Blanxer uses the site in:

- the tracking link it generates (dashboard copy, `get_tracking_link`);
- the confirmation emails of orders created in the dashboard, as leads or through Sambad (orders placed on the site use the site's own `url`);
- the delivered email;
- flash-sale alerts: the alert links to the `url` the site sent with "Notify me", which is kept only when it is on the store's domains, the saved link included;
- the product feed and the catalog sitemap.

Whether SMS short links follow it is not yet verified. Clearing the link puts these back on the custom domain if the store has one, else the subdomain (the delivered email falls back to `<sub>.blanxer.com`).

This tool ships with the BlanxerAPI release of the Blanxer MCP. Until your MCP lists it, the merchant pastes the link in the Blanxer dashboard → avatar menu → BlanxerAPI → Your website (rolling out).

## Confirm before bulk changes (rule 13)

Store data is live and shared with the dashboard, POS and mobile app. Before any change that touches many records (SEO for many products, imports, category renames, delivery charges):

1. Run the tool with `dry_run: true` where it has one, or list what will change.
2. Show the merchant the list or a sample, with counts.
3. Apply only after a clear yes.

The MCP's own confirmations still apply on top of this. Never invent product facts, reviews or claims in SEO text; use the product's own data and the merchant's words.

## What not to do

- **Don't use the page-builder tools on a custom site** (rule 12). These change the **Blanxer-hosted** site only:
- `blanxer_add_section`, `blanxer_update_section`, `blanxer_move_section`, `blanxer_remove_section`, `blanxer_duplicate_section`
- `blanxer_apply_page_template`, `blanxer_create_page`, `blanxer_update_page`, `blanxer_duplicate_page`, `blanxer_delete_page`
- `blanxer_update_navigation`, `blanxer_update_footer`

The custom site's design, menus and footer live in its code.

**Exception: blog post bodies.** `blanxer_create_blog_post` makes an empty post; write its body with `blanxer_add_section` / `blanxer_update_section` using `{ post_id }`. That is content the site shows (the post's `sections`), so use them for blog posts.
- Don't use the MCP from the site's code, and don't put an MCP token anywhere.
- Don't change `store_visibility` unless the merchant asks (see [Deploy → Retiring the old subdomain site](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#retiring-the-old-subdomain-site)).
- Don't put product photos in the site's repo; upload them to Blanxer.

---



# Testing

Test the site before it goes live, and once more after. There are three tools: the `0000000000` test order (any store), the sandbox store on `api-dev`, and the live check.

## 1. Run the check command

```bash
npx blanxer-storefront check
```

Fix every failure first. What it checks: [Package → check](https://developers.blanxer.com/api-docs/package.md#check).

## 2. Test orders that create nothing

On **any** store, including the merchant's real one, an order with:

- `customer_phone_number` = `0000000000`, or
- a `customer_email` containing `mailinator.net`

returns HTTP 200 `{"success": true}` and **creates no order**: no stock change, no SMS, no email, nothing in the dashboard.

- The body is validated **before** this check, so every other field must be valid. Use it to test validation messages too: leave the name empty and you get the real error.
- The response has no `_id`. The package's checkout stops there and shows "Test order accepted — no order was created for this test phone/email.": no payment start, no redirect, nothing in `sessionStorage`.
- It can't test payments, stock holds or the tracking page, because no order exists.
- Test orders still count toward the limit of 5 orders per 10 minutes per store and IP. After 5, wait or you get HTTP 429.
- Applying a coupon is real even here: for a coupon with a usage limit, each successful apply holds one use for about 12 seconds. Don't test a coupon with very few uses left.

Use it for the form, the place select, delivery charges, COD availability per place, coupons (apply, then place), and that the request leaves from the browser (rule 5).

## 3. The sandbox store

A sandbox store on `https://api-dev.blanxer.com` is planned for BlanxerAPI: every gateway in test mode, products with variants, weights and custom fields, delivery places with and without COD, coupons and a live flash sale. Its subdomain will be listed here when it is ready.

**Until then, check the gateway and QR screens live** (see [the live check](#4-the-live-check)): the `0000000000` order creates nothing, so it never opens them.

Point the site at it:

```bash
BLANXER_API=https://api-dev.blanxer.com BLANXER_STORE=<sandbox subdomain> ./node_modules/.bin/next dev
```

On the sandbox, place:

| Order | Expect |
|---|---|
| One COD order | Lands on `/track/<id>?from=checkout` with the congratulations banner |
| One order per gateway the **real** store has on | Returns to `/payment/success`, then `/track/<id>` |
| One cancelled payment (cancel on the gateway page) | Returns to `/payment/failed` |
| One QR order left to expire | The timer runs out, "QR is expired" shows, and the hold is released (the units are buyable again) |
| One QR order closed with ✕ → "Yes, cancel payment" | The hold is released at once |

Notes:

- Run the gateway tests on a deployed preview, or locally on `http://127.0.0.1:3000`. eSewa, Khalti and FonePay reject `http://localhost` as the return `url` (HTTP 400 `Valid Return URL is required`).
- On `api-dev`, Checkout by Fonepay uses Fonepay's development credentials and asks for 1.1, not the order total.
- An eSewa store in test mode has `product_code` `EPAYTEST` and posts to `rc-epay.esewa.com.np`.
- The `api-dev` database is shared with Blanxer's own development. Only create orders on the sandbox store.

## 4. The live check

After deploying and saving the link in Blanxer:

1. Open, on the live site: home, a product, a category, `/checkout`, `/payment/success`, `/payment/failed`, and a real `/track/<id>` (the merchant can give you one from the dashboard).
2. With the merchant's OK, place **one real COD order** on the real store with the merchant's own phone number. Check it reaches `/track/<id>`, appears in the dashboard, and the confirmation email links to the new site.
3. Have the merchant **cancel it in the dashboard**, so stock goes back and it doesn't count as a sale.
4. For one online method the store uses, place a real order and open the gateway or QR screen, then stop without paying. Close the QR screen with ✕ → "Yes, cancel payment" (that releases the stock hold). Have the merchant cancel the order in the dashboard.
5. Run Lighthouse (mobile) on home, a product and checkout: ≥ 90, LCP < 2.5 s.
6. Check `/sitemap.xml`, `/sitemap-catalog.xml` (its links must be on the live domain) and `/robots.txt`.

Don't make real online payments yourself. If the merchant wants to confirm a gateway, they pay a small real order themselves and refund or cancel it in Blanxer.

---



# Deploy to Cloudflare

The site runs on Cloudflare Workers in the **merchant's own Cloudflare account**. Blanxer doesn't host it and never gets access to that account.

## The toolchain

- Next.js 16, App Router, TypeScript.
- [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), which runs the real `next build` and turns the output into a Worker.
- `wrangler`, Cloudflare's CLI.

The starter already has `wrangler.jsonc`, `open-next.config.ts` and these scripts:

| Script | Runs |
|---|---|
| `dev` | `next dev` (local, Node) |
| `build` | `next build` |
| `preview` | `opennextjs-cloudflare build && opennextjs-cloudflare preview`: the real Worker, locally |
| `deploy` | `opennextjs-cloudflare build && opennextjs-cloudflare deploy` |

This page calls the binaries directly (`./node_modules/.bin/opennextjs-cloudflare ...`); the scripts do the same.

Deploy to **Workers**, not Cloudflare Pages. Don't swap the adapter: Blanxer tests the checkout against this setup.

## Configuration

The site reads its settings from `.env`. OpenNext copies `.env` into the Worker at build time, so the same file works locally and deployed. None of these is a secret.

| Variable | Required | Meaning |
|---|---|---|
| `BLANXER_STORE` | Yes (`check` fails without it) | The store's subdomain, e.g. `mystore` |
| `BLANXER_API` | No | API base, default `https://api.blanxer.com` (`https://api-dev.blanxer.com` for sandbox testing) |
| `SITE_URL` | No | The site's public origin, for canonical links, `robots.txt` and the sitemap index. Default: the website link saved in Blanxer (`storefront_url`) |
| `NEXT_PUBLIC_BLANXER_IMAGE_LOADER` | No | Product photo resizing: `wsrv` (default), `cloudflare` or `none` |

**Before the first deploy, rename the Worker** in `wrangler.jsonc`: set `name` to the merchant's site name, and the `WORKER_SELF_REFERENCE` service binding's `service` to the same value. The name is part of the `workers.dev` link.

```jsonc
{
"name": "mystore",
"services": [{ "binding": "WORKER_SELF_REFERENCE", "service": "mystore" }]
}
```

Keep the rest of the starter's `wrangler.jsonc` as it is. No other configuration is needed: the public API needs no key, and nothing secret belongs in the Worker (rule 6).

### Caching on the Worker

The starter has no R2 or KV cache configured, so a new merchant can deploy without creating Cloudflare resources. Pages render on each request, and the package keeps API reads in memory for 60 seconds per Worker instance. For full ISR, create an R2 bucket and turn on the R2 incremental cache: the steps are commented in the starter's `open-next.config.ts` and `wrangler.jsonc`.

## Sign in to Cloudflare

```bash
npx wrangler login
npx wrangler whoami
```

- **Normal case:** a browser opens. The merchant signs in to **their own** Cloudflare account (a free account is enough) and approves access. You never see their password. `whoami` shows which account you are on; confirm it with the merchant.
- **No browser** (remote machine, CI): the merchant creates an API token in Cloudflare → My Profile → API Tokens → Create Token → template **Edit Cloudflare Workers**, and sets it in **their own** terminal:

```bash
export CLOUDFLARE_API_TOKEN=... # and CLOUDFLARE_ACCOUNT_ID=... if they have several accounts
```

Don't ask them to paste the token into the chat, and never write it to a file in the repo.

## Worker size

```bash
./node_modules/.bin/opennextjs-cloudflare build
```

The build prints the Worker's size. The **compressed** size must be under:

- **3 MiB** on the Workers **free** plan;
- **10 MiB** on the Workers **paid** plan ($5/month).

Static assets (images, CSS, client JavaScript chunks) don't count toward it. If the Worker is over 3 MiB, tell the merchant **before** deploying and offer:

- remove heavy server-side dependencies (large UI kits, date and icon libraries imported whole, markdown or PDF libraries on the server);
- move work out of server code where it isn't needed;
- or the $5/month paid plan.

## Preview, then deploy

```bash
./node_modules/.bin/opennextjs-cloudflare build && ./node_modules/.bin/opennextjs-cloudflare preview # the real Worker, locally
./node_modules/.bin/opennextjs-cloudflare build && ./node_modules/.bin/opennextjs-cloudflare deploy
```

The deploy ends with the live link: `https://<worker-name>.<account-subdomain>.workers.dev`. Then check, on that link:

- the home page, a product, a category and `/checkout` load with real data;
- `/payment/success`, `/payment/failed` and `/track/<a real order id>` exist (not 404);
- `/sitemap.xml`, `/sitemap-catalog.xml` and `/robots.txt` respond.

## Link the site to Blanxer

1. Save the link: `blanxer_set_storefront_url { url: "https://<the workers.dev link or the custom domain>" }` through the MCP. That call is a preview with a `confirm_token`; after the merchant's yes, apply it with `{ dry_run: false, confirm_token }`. Or the merchant pastes it in the Blanxer dashboard → avatar menu → BlanxerAPI → Your website (rolling out).

Blanxer then uses it for the tracking link it generates, the delivered email, flash-sale alerts, the product feed and the sitemap. See [MCP for your website](https://developers.blanxer.com/api-docs/mcp-for-website.md#blanxersetstorefronturl) for the full list.
2. Register the product feed `https://api.blanxer.com/public/product-feed/<store_id>.xml` with Meta Commerce Manager and/or Google Merchant Center.
3. Verify the site in Google Search Console and submit `https://<site>/sitemap.xml`.

Details for 2 and 3: [SEO and tracking](https://developers.blanxer.com/api-docs/seo-and-tracking.md).

## Custom domain (optional)

1. The domain must be a zone on the merchant's Cloudflare account. In Cloudflare: **Add a domain**, then change the nameservers at the registrar if Cloudflare asks. This can take a few hours.
2. **Workers & Pages** → the Worker → **Settings** → **Domains & Routes** → **Add** → **Custom domain** → enter `mystore.com` (and `www.mystore.com` if wanted). Cloudflare creates the DNS record and the certificate.
3. Pick one host as the main one and redirect the other to it (a Cloudflare redirect rule, `www` → apex or the reverse).
4. Update the Blanxer link (step 1 above) to `https://mystore.com`.

**If the domain currently points at Blanxer** (it appears as `custom_domain` in `check_domain`), moving it to the Worker switches every shopper on that domain from the Blanxer-hosted site to the new site, at once. Explain that, and let the merchant decide when.

## Retiring the old subdomain site

Optional, the merchant's choice, and **only after the link is saved**.

- Through the MCP: `blanxer_update_appearance { store_visibility: 'hidden_on_subdomain' }`;
- or in Blanxer: **Appearance → Branding → Site under construction → Sub-domain**.

Tell the merchant plainly, before switching:

- **every** page on `<sub>.blanxer.io` shows a placeholder, **including tracking and payment links sent before today**. There is no exception for old `/track` or `/payment` links;
- new orders' links go to the new site;
- it can be switched back at any time (`store_visibility: 'live'`).

The switch only affects the Blanxer-hosted pages. The API, and so the custom site, keeps working: `check_domain?domain=<sub>` still answers.

## Redeploying later

1. Edit the code.
2. `./node_modules/.bin/next build` and `npx blanxer-storefront check`.
3. `./node_modules/.bin/opennextjs-cloudflare build && ./node_modules/.bin/opennextjs-cloudflare deploy`.

Store data changes (products, prices, stock, SEO text, delivery charges, coupons) need **no** redeploy. They show on the site within about a minute.

## Hand-over

Leave a `README.md` in the site repo for the merchant (or their developer): how to run it locally, how to change the design, how to redeploy (`opennextjs-cloudflare build && opennextjs-cloudflare deploy`), which Cloudflare account it lives on, which domain, and that products and SEO are edited in Blanxer, not in the code.

---



# Troubleshooting

Find the symptom, then the fix. API errors come back as HTTP 400 `{"message": "..."}` unless noted; validation errors as `{"error_type": "zod_validation", "fields": {...}}` or `{"fields": {...}}`.

## Checkout and payments

### The shopper gets a 404 after paying

The gateway returned to `<url>/payment/success` or `<url>/payment/failed`, and that page doesn't exist on the site.

- Add `/payment/success`, `/payment/failed` and `/track/[id]` at exactly these paths, with the package's `PaymentSuccess`, `PaymentFailed` and `OrderTracking` (rule 3).
- `url` must be the site's origin with no path and no trailing slash: `window.location.origin`. Blanxer appends `/payment/success` to it as is.
- Never hardcode `url` (rule 4). A hardcoded `workers.dev` origin sends shoppers back to the old host after the custom domain is added.

### `/payment/success` sends the shopper to the home page instead of their order

The success page reads the order id from `sessionStorage['checkout_order_id']`, which only exists on the origin where the checkout ran.

- Serve the site on **one** host. Redirect `www` to the apex (or the reverse) so checkout and success are on the same origin.
- Don't clear `sessionStorage` in your own code.
- A shopper who finished paying on another device or browser has no session there; they land on `/`. Their order is fine and the confirmation email links to `/track/<id>`.

### `Selected delivery city not found, please try again`

The order's `customer_address_city` doesn't exactly match a place name in the store's delivery table.

- Fill the place select only from `GET /public/delivery_charge/<store_id>`. Never type place names into the code.
- Send the place **name** as `customer_address_city`, not the address.
- The merchant may have renamed a place; the site's cached table is at most a minute old. Reload.

### `Cash on delivery is not available for the selected delivery location`

The order asked for COD at a place where the store turned COD off.

- COD is allowed only when the place's flag is `true` or `'Y'`. A check like `!!cod` treats `'N'` as yes: that is a known bug in the Blanxer-hosted storefront; the package doesn't copy it.
- When the shopper changes the place and COD disappears from the list, the selected method must change too (the first available one).

### The coupon shows a discount, but the order has none

The order was sent with the coupon **code** (`"coupon": "DASHAIN10"`). The server only reads `coupon` when it is longer than 20 characters (an id), so a code is ignored **silently**: no discount, no error.

- Send the `_id` returned by `POST /public/coupon` (rule 2: use the package's checkout, which does this).
- Compare the order response: `total_price` already has the discount taken off.

### Coupon errors

| Message | Cause |
|---|---|
| `Coupan not found` | No coupon with that exact code in this store. Codes are case-sensitive: the input is upper-cased, but a `?promo=` link is sent as written, so `?promo=dashain10` fails for `DASHAIN10` |
| `Coupon not found` (at order time) | The coupon `_id` sent with the order no longer exists |
| `Coupon is inactive` | Turned off in Blanxer |
| `All the available coupons have been used.` | Used up. For a coupon with a usage limit, each successful apply also holds a use for about 12 seconds, so on the last use an order placed right after Apply can fail with this. Wait a few seconds and place it again |
| `Coupon code not available` / `Coupon code is expired` | Before its start / after its end |
| `Coupon is not applicable to any products` | A category coupon and no line in those categories |
| `Coupon is only applicable for order value above N` | Subtotal + customization + delivery under the minimum |
| `Only cash on delivery can use this coupon` / `Only online payment method can use this coupon` | Payment method restriction |
| `This coupon is not valid for <place>` | Place restriction |

### `Valid Return URL is required`

`POST /payment/esewa/init`, `/payment/khalti/init` and `/payment/fonepay/init` reject `http://localhost:3000` as `url`. Test on `http://127.0.0.1:3000`, on the OpenNext preview opened via `127.0.0.1`, or on the deployed site.

### `Variant selection required for this product` / `Either of the selected product has been modified, please add to cart again`

- The cart line has no `variant`, or a variant `_id` that no longer exists (the merchant edited the variants).
- Make sure `AddToCart` stores the variant **`_id`**, not its name.
- For old carts: drop the line and ask the shopper to add it again.

### `Please choose a print for <name>`

The product has a required print add-on, and the line has no `print_id`. The package has no print picker yet, so it can't sell that product. Ask the merchant to make the print optional, or leave the product off the site for now. See [Checkout → Print add-on products](https://developers.blanxer.com/api-docs/checkout.md#print-add-on-products).

### `Either of the selected product is already deleted` / `... is out of stock`

The product is no longer Active, or the stock is lower than the quantity (and it doesn't continue selling). Refresh the cart from the product data.

### `The last units of an item in your cart are in other shoppers' checkouts right now...`

Other shoppers hold the last units while they pay. It clears within the hold time (5 minutes; 2–5 during a flash sale). Show the message as is.

### HTTP 429 when placing orders

More than 5 order requests in 10 minutes from one IP for one store. Every request counts, including `0000000000` test orders and failed ones. The body is plain text (`Too many requests, please try again later.`), not JSON; handle that. If **every** shopper hits it, orders are being sent from the server (one shared Worker IP for everyone): move the call to the browser (rule 5).

### The QR payment never confirms

- The page checks while the tab is **visible** (every 5 s for Fonepay QR, 10 s for Checkout by Fonepay) and when the shopper returns to it. Ask them to come back to the tab or press "Check payment".
- Never close the QR or release the hold on tab switch; shoppers pay in their banking app with the QR open.
- `Payment not received` from the check endpoint only means "not yet".

### The eSewa page shows an error from api.blanxer.com after the shopper cancels

eSewa sends both success and failure back to the same API endpoint. A return without eSewa's `data` parameter may end on an API error page instead of `/payment/failed`. This is on Blanxer's side and is being verified; the order stays `Inactive`, and the shopper can go back to the site.

### Khalti shows an error before redirecting

Khalti's own error text is passed through (for example a minimum amount or a configuration problem). Show it; the merchant may need to fix their Khalti settings in Blanxer. If it reads `[object Object]`, Khalti returned a structured error; check the store's Khalti keys in Blanxer.

## Catalog and data

### A Draft or POS-only product page is visible

`GET /product/public/<store_id>/<slug>` also returns non-Active (`Draft`, `Archived`) and POS-only products. The page must call `notFound()` unless `status === 'Active' && channel !== 3`; the package's `getProduct()` returns `null` for them. See [Catalog → One product](https://developers.blanxer.com/api-docs/catalog.md#one-product).

### A product page shows "Product not found" as an error instead of a 404

An unknown slug is HTTP **400** `Product not found`, not 404. Catch it and call `notFound()`.

### Prices or stock lag behind the dashboard

The site caches data for 60 seconds. The API caches the product lists for up to 1 hour and clears them when the merchant saves products, categories or settings. Orders don't clear it, so stock in lists can lag by up to an hour; the product page itself isn't cached by the API. The checkout always charges the current server price and checks the current stock.

### `Domain not in use`

`BLANXER_STORE` is wrong. It is the subdomain only (`mystore`), not `mystore.blanxer.io` and not the custom-site domain.

### Server-side reads fail with Cloudflare error 1010

Public reads have been checked to work from plain `fetch`, `curl` and Node. The package sends a normal `User-Agent`. If a Worker still gets 1010, report it to Blanxer with the time and URL; don't work around it with a proxy.

## SEO

### The catalog sitemap or product feed links to `<sub>.blanxer.io`

The site link isn't saved in Blanxer. Call `blanxer_set_storefront_url` (preview, then `{ dry_run: false, confirm_token }`), or the merchant saves it in BlanxerAPI → Your website. The API uses it on the next request, but HTTP caches (`max-age=3600`, plus `stale-while-revalidate`) and the site's own `/sitemap-catalog.xml` can serve old links for an hour or more.

### Search Console says the verification tag is missing

- Check the home page source for `<meta name="google-site-verification" ...>`. The site must render the store's `meta_tags` plugin (`verificationMetadata(store)`).
- After `blanxer_set_site_verification`, wait about a minute for the API and site caches.
- The property in Search Console must be the exact host the site is served on (`https://mystore.com/`, not `www.` if that redirects).

### The shopper got no confirmation email

- With `checkout.receiver_info` on and a sender name filled, the email goes only to `sender_email`; none is sent when that is empty.
- Online orders are emailed only once paid. COD orders are emailed when created.

### Confirmation emails link to the wrong site

The email uses the `url` sent with **that** order. Orders placed before a domain change keep the old link. Make sure the checkout sends `window.location.origin`.

## Deploy

### The Worker is over 3 MiB

The Workers free plan allows 3 MiB compressed. Tell the merchant before deploying, then:

- remove heavy server-side dependencies (whole icon sets, UI kits, date libraries, markdown/PDF tools used on the server);
- keep large libraries out of server components;
- or move to the $5/month Workers paid plan (10 MiB).

See [Deploy → Worker size](https://developers.blanxer.com/api-docs/deploy-cloudflare.md#worker-size).

### `wrangler` deploys to the wrong Cloudflare account

Run `npx wrangler whoami`. If it's not the merchant's account, `npx wrangler logout`, then `npx wrangler login` and have the merchant sign in. With several accounts, set `CLOUDFLARE_ACCOUNT_ID`.

## Images

### Images too big / the image budget fails

Every file in `public/` must be ≤ 300 KB and ≤ 2560 px wide, as AVIF/WebP, rendered with `next/image` and a size. Re-run `npx blanxer-storefront images` with the right export width for the slot (hero 2560, banner 1600, card 800). Never commit originals. Product photos belong in Blanxer, loaded through `blanxerImageLoader`. See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md).

## `npx blanxer-storefront check` failures

| Failure | Fix |
|---|---|
| Missing route `/checkout`, `/payment/success`, `/payment/failed` or `/track/[id]` | Add it at that exact path with the package component |
| Secret found | Remove it from code, `.env` and the build. No key is ever needed (rule 6) |
| `/customer/auth` or `/customer/account` call, or a login/account/wishlist/rewards page | Remove it (rule 7). Only `/customer/stock-alert` is allowed |
| Order or payment call outside the browser | Move it into a client component; no server actions or route handlers for orders, coupons, payments, holds or stock alerts (rule 5) |
| Image budget | See above |
| No image marked as main (warning) | Add `preload` to each page's main (LCP) image. See [Images and speed](https://developers.blanxer.com/api-docs/images-and-speed.md#loading-images) |
| Lighthouse under 90 / LCP over 2.5 s | See [Images and speed → When the check fails](https://developers.blanxer.com/api-docs/images-and-speed.md#when-the-check-fails) |}}