Portal storefronts

A portal storefront is a shop served on one of your xMatix portals: visitors browse your published catalogue, fill a cart and check out, and every order joins the same order book as the rest of your sales. It sits between two pieces of setup. Before it, an administrator builds a portal site and a commerce store. After it, orders flow into the normal sales pipeline of allocation, delivery, invoicing and collection. This page explains how a site becomes a storefront, what a visitor sees, and how an administrator sets it up and keeps it running. There is no screenshot, because the storefront only exists on a published portal in your own organization.

Overview

A portal can do two different jobs, and the difference decides what a visitor can do:

A site becomes a storefront when an active commerce channel names it in its Portal Site field. Nothing on the portal itself switches the storefront on: the link lives on the channel.

When to use it

• You want dealers or retailers to reorder on their own, see their credit, statements and schemes, and track deliveries.
• You want consumers to buy from a branded site, as guests or with an account.
• You run several audiences (a dealer portal and a consumer shop, for example) and want each to have its own order history.

Dealers who order through back-office channels, such as the Product Catalogue cart inside the apps, purchase-order handoff or field-sales capture, can keep doing so. Those channels are described in Dealer ordering. The storefront adds a self-service lane beside them; it does not replace them.

How xMatix handles it

The storefront takes over the portal's home address

When a visitor opens the portal's root address, xMatix checks two things in order:

1. Is a page published at /? If so, that page is shown. A published home page always wins, even on a storefront portal.
2. Is an active commerce channel linked to this site? If so, the storefront is shown.

If neither is true, the address answers "not found". The storefront lives at the root address only. It moves between its screens without changing the address, so other paths on the portal still show your published pages.

If more than one active channel names the same site, the channel created first is used. Keep one active channel per storefront portal. The channel's Channel Type is not checked here: any active channel with a Portal Site turns that site into a storefront, so give the link only to a portal channel.

What a visitor sees

A visitor who is not signed in lands on the storefront's public home. It presents the range, offers a pincode check and invites the visitor to sign in. The menu offers Home, Products, Cart and Contact. A guest can add to the cart and check out: the checkout asks them to confirm their email (or phone) with a one-time code before payment. Any other screen asks them to sign in first with the message "Please login to continue".

A signed-in customer lands on their dashboard, which shows their credit, targets and schemes. The menu offers Home, My Orders, Products, Cart, Contact and More. Under More they find:

• Business profile, for GSTIN, contacts and licences;
• Payments & ledger, for their statement, credit notes and outstanding amount;
• Schemes & offers, for live schemes and their progress;
• Help & support, to call or raise a ticket;
• Contact us.

The storefront takes its name, logo and colours from the portal's published theme.

Catalogue, prices and stock

The catalogue a storefront shows is a published copy of the channel's store: products, content and displayed prices change only when the store is published again (see The catalogue is published, not queried). Stock on the product cards is read live.

The cart prices each line at the moment it is built and again at checkout:

1. A price set on the store's own catalogue entry wins.
2. Otherwise the cart uses a price list named for the signed-in customer, then one for their customer account group, then a general list. It never uses a list the shopper is not entitled to.

If the total moved since the shopper last saw it, checkout stops and shows the new price. This means two signed-in dealers can see the same displayed price while browsing and still be charged their own terms in the cart.

Each portal is its own boundary

A tenant can run several portals, and they stay separate in four ways:

• Membership. Inviting a user to a portal, or their self-signup on one, makes them a member of that portal. On a portal they do not belong to, they are treated as an anonymous visitor.
• Audience. External logins reach only portal and storefront surfaces. The internal workspace refuses them with "This account belongs to a partner portal and cannot use the tenant workspace APIs.", whatever security profile the account carries.
• Order books. Each order is stamped with the channel it was placed on. On a channel linked to a portal site, My Orders shows only that channel's orders, and opening another portal's order fails as not found. A headless or unlinked channel shows the account's whole order history.
• Money stays whole. Payments, invoices, credit and the ledger are account-level on purpose. What a customer owes is one number however many portals they shop through, so a credit limit cannot be evaded by switching storefronts.

Signing up and signing in

With Self-service signup on, a visitor can create a login from the storefront. With Create customer on signup on (the default), the signup also creates a consumer account and a linked contact, so the storefront can find their account straight away. The full behaviour, including how a guest who ordered can claim their order history, is in Consumer self-signup and accounts and Visitors and signup.

Paying

At checkout the shopper picks a payment method:

• Card or UPI through the channel's payment gateway account, or your default account when the channel names none. Without any gateway account these options are not offered. See Payments and gateways.
• Pay on credit ("Use your sanctioned limit"), offered only to a signed-in customer whose account has credit available. The order lands as Draft and goes through your normal approval.
• Cash on delivery, only on channels that switch it on.

Prerequisites

• Enable Commerce is on (Setup → Feature Hub → Commerce → Settings, General).
• The Portals module is on, and you have the Manage portals capability. See xMatix Portals.
• A store with its categories and catalogue entries, and a published catalogue for it.
• A commerce channel for the storefront. See Direct-to-consumer selling.
• A payment gateway account if you take card or UPI payments.

Procedure

Step 1 — Create the portal site

Open Setup → Feature Hub → Portals → Portals and click New. Enter a Label and keep or change the Slug (portal hostname label), then click Create. The site opens on its General tab. The full steps are in Build a portal.

Step 2 — Decide who may visit

On the General tab:

• Turn Anonymous visitors on for a consumer shop or any storefront that guests should see. With it off, a visitor who is not signed in to this portal gets "not found" for the whole site, including the storefront.
• Turn Self-service signup on if visitors may create their own login, and keep Create customer on signup on so each signup gets a customer account.
• Leave Learning off. A portal is either a storefront or a learning portal, never both.

Save.

Step 3 — Leave the home address free

Do not publish a page at path / on this site. A published home page replaces the storefront. Other pages, for example an About or Terms page at their own paths, can sit beside it.

Step 4 — Link the channel to the site

The channel's Portal Site field is on the channel's record page (in the Serving panel) but not on the shipped create form, and the channel record has no Edit button. Set it in one of these ways:

• ask the Setup Copilot to link the channel to the portal by name;
• set the channel's Portal Site to the portal's identifier through the Data API. The identifier is the last part of the portal's address in Setup, /setup/portals/<identifier>;
• add Portal Site to the channel's create form, and an Edit action to the channel, so administrators can maintain it on screen. See Commerce screens and records.

If the site is already a learning portal, the save is refused (see Common problems).

Step 5 — Publish the catalogue and the portal

1. Publish the channel's store so it has a live catalogue (see Stores).
2. On the portal record, click Publish. The Draft tag beside the address disappears and the address starts answering.

Step 6 — Check it as a visitor

Open the portal's address in a private browser window. You should see the storefront's public home with Home, Products, Cart and Contact. Open Products: the published range appears. Add an item to the cart and go through checkout up to the payment step. Then sign in as a test customer who is a member of the portal and check that My Orders and More appear.

Step 7 — Take the storefront offline

Choose the scope:

• Stop selling but keep the portal: switch the channel's Is Active off (through the same route as Step 4). The site goes back to being a content portal, and its root answers "not found" unless a page is published at /.
• Take the whole site down: click Unpublish on the portal record. The portal stops being served to all visitors immediately.

Fields

The storefront is configured across two records. These are the settings that matter for it.

The full channel field list is in Direct-to-consumer selling, and the portal fields in xMatix Portals.

Business rules

• The storefront is served only at the portal's root address, and only when no page is published at / and an active channel names the site.
• With several active channels on one site, the earliest-created channel is used.
• A channel cannot be linked to a site that an active learning portal already uses, and a learning portal cannot use a storefront's site.
• Order history on a portal-linked channel is limited to that channel's orders. Credit, invoices, payments and the ledger are not.
• The displayed catalogue changes only on publish. Stock badges are live. Cart and checkout prices are recalculated, and checkout refuses a total that moved.
• Pay on credit needs a signed-in customer with credit terms and enough available credit.
• Guests can buy only when Anonymous visitors is on. There is no separate switch for guest checkout.

Example

A tile distributor wants its retailers to reorder online.

1. The administrator creates the portal Retailer Shop with slug retailer-shop, leaves Anonymous visitors off (only retailers should see it), and keeps Self-service signup off, because retailers are invited.
2. The store Retail Range already exists and is published. A portal channel Retailer Web over that store is linked to Retailer Shop through the Setup Copilot.
3. The administrator publishes the portal and invites two retailers from the portal's Members tab.
4. A retailer signs in and lands on the dashboard showing their available credit. They add four boxes of floor tiles under Products, check out with Pay on credit, and see their order under My Orders.
5. In the back office, the order appears in the sales order list as Draft, stamped with the Retailer Web channel, and goes through approval like any other order.

Training

Practice exercise

In a sandbox:

1. Create a portal Training Shop, turn Anonymous visitors on and publish it.
2. Open its address. Expected result: "not found", because no page is published at / and no channel is linked.
3. Link an active portal channel with a published store to the site.
4. Open the address again in a private window. Expected result: the storefront's public home with Home, Products, Cart and Contact.
5. Publish a page at /. Expected result: the page replaces the storefront. Unpublish or remove the page to get the storefront back.

Quick reference

• The link is the channel's Portal Site, not a setting on the portal.
• The storefront shows only at the root address, and a published / page wins.
• One active channel per storefront site; the oldest wins if there are several.
• Anonymous visitors off means no guests and no guest checkout.
• Prices shown while browsing change only on publish; the cart reprices.
• My Orders is per portal; credit and the ledger are per account.
• A portal is a storefront or a learning portal, never both.

Permissions

External logins never get into the internal workspace, whatever profile they carry.

Configuration

Common problems

The portal address says "not found"

Check, in order: the portal is published and Active; Anonymous visitors is on, or you are signed in as a member; an active channel names the site in Portal Site. After a change, allow up to five minutes for the address to pick it up.

The portal shows a page instead of the shop

A page is published at path /. A published home page always wins. Unpublish it or move it to another path.

"No catalogue published yet"

The channel's store has no live catalogue. Publish the store, then reload. The underlying message is "This storefront has not published a catalogue yet."

"This storefront has no catalogue configured."

The channel has no Store. Set one on the channel.

"This portal is already the learning portal '…'. A storefront needs a portal of its own: create another portal for this channel."

The site you named in Portal Site is an active learning portal. Create a separate portal for the storefront.

"This sign-in does not belong to this portal."

The shopper signed in with a login that is a member of another portal. Invite them to this portal from its Members tab.

"Please login to continue"

A guest tried to open a screen that needs an account, such as My Orders. They need to sign in, or sign up where Self-service signup is on.

"This order is larger than your available credit"

The order exceeds the account's available credit. The customer can clear an invoice or choose another payment method. "Sign in to buy on account." and "This account has no credit terms." mean the shopper is a guest or the account has no credit limit.

Card and UPI options are missing at checkout

No payment gateway account applies to the channel. Set one on the channel or mark a default account. See Payments and gateways.

A customer cannot see an order they placed on our other portal

That is by design: each portal-linked channel keeps its own order book. The order is visible on the portal it was placed on, and in the back office.

Common questions

Can the storefront show each dealer their own prices?

The browsing catalogue shows one displayed price per listing, the same for every visitor, because it is a published copy. Account-specific terms apply in the cart: a price set on the store's catalogue entry wins, and otherwise the cart uses a price list named for the signed-in customer, then one for their account group, then a general list. Checkout always reprices against current rules and stops if the total changed, so the shopper confirms the real amount before paying.

Can a dealer place an order from a portal page instead of the storefront?

No. Portal pages and published data views are read-only for external visitors: an embedded list shows records but never writes. Ordering happens in the storefront, which appears at the portal's home address once a channel is linked. You can still publish read-only pages beside the storefront at other paths, for example a price circular or a list of the dealer's own records through an authenticated data view.

Is the data on a storefront a copy that can go stale?

Partly. Published data views on portal pages read live data at request time. The storefront catalogue's products, content and displayed prices are a published copy that changes only when the store is published again. Stock on the product cards is read live, and the cart and checkout always reprice against current rules.

Can one portal serve two channels?

Only one at a time. If several active channels name the same site, the one created first is used and the others are ignored by that site. Run separate portals for separate audiences, each with its own channel. Each then keeps its own order history.

Do guests need an account to buy?

No, when Anonymous visitors is on. A guest confirms their email or phone with a one-time code during checkout. Afterwards they can create an account from the order confirmation and keep that order's history; see Consumer self-signup and accounts.

Related topics

• xMatix Portals
• Build a portal
• Portal security
• Direct-to-consumer selling
• Stores
• Catalogue and pricing
• Payments and gateways
• Consumer self-signup and accounts
• Dealer ordering
• Partner microsites and order routing