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

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

#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:

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.

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:

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

const NAMED: Record<string, string> = { 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 (
    <html lang="en" style={{ ['--bx-primary' as string]: primary }}>
      <body>{children}</body>
    </html>
  );
}

#Font

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

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/<slug> 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/<slug>, /product/<slug>, /brand/<slug>, /brands, /sale, /search, /blogs, /blog/<slug>, /forms/<slug>. 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:

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), 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).
• 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.