How a block gets its data

Site Builder blocks that fetch their own data take it from a source you choose while you configure the block. This article explains the product and document sources a block can use and what each one needs.

Each block is built once and reused across clients whose ERP systems expose their data in different ways, so a block cannot know in advance where its data comes from. Instead, you pick a source from the platform capability catalog, and the resulting address is saved in the block itself. On the live storefront the block calls the address it saved and does not consult the catalog, so the catalog going offline does not affect pages that are already live.

The block's panel asks four things in a fixed order: which family of sources to browse, which source to use, where each parameter's value comes from, and which template controls the block's appearance. The family you browse under only helps you locate a source and is not part of what the block stores, so reaching one source by two routes gives the same saved page. You see the parameters section only for sources that require a parameter, so its absence on a block is normal and not a setup error. A document's totals block has nothing to configure as a source; it displays the figures delivered with the header block's data.

The Page Editor tab of a client page groups its components under Basic, Widgets, Dynamic Product Details, Auth, Profile, Pages, Documents and Apps.

The sources you can choose

When the select offers no client-defined entries, expect its options to sit under family headings such as products, catalog and documents, which keeps product sources apart from brand sources. Read the description the catalog gives for a source before you choose it, because that description documents the pitfalls of the source. To compare sources without selecting them, hover over the information icon beside each option; its tooltip repeats that description.

Product sources

Prices and stock levels are never part of a product list's rows; each is requested separately for the products being shown.

Source	What it provides	What to know
Catalog products	The client's products for one chosen category, including everything in the categories beneath it, which category pages use for their product lists.	When several category ids are given, only the last one is used and the ones before it are ignored. Its rows omit price and stock, which have to be fetched through their own sources.
One product	The full record of one product: what a list row holds, plus details such as brand, images, packages, attributes, tabs, links and files that only this source returns.	Nothing needs choosing on the product page itself, where the product id comes from the URL; a product card elsewhere needs the id entered when you set it up. It answers with the product itself rather than a list.
Live prices	Each requested product's sku, price, discount, total and currency, worked out by the pricing sources the client has configured.	A guest receives nothing unless the shop shows base prices to guests. Match results to products by sku, not by their position in the reply, because a product with no resolvable price simply has no row.
Promoted products	The client's current promotional selection, the kind of list that fills a home-page sale carousel or promotions strip.	The rows depend on who is signed in, so what a signed-in customer receives can differ from what the block shows to visitors in general.
Recently viewed	The shopper's own product-view history, most recent first.	Only a signed-in shopper gets rows back; every other visitor sees an empty block. You cannot set the look-back period or row count on the block, since the client configures both, and you should keep the sequence the rows arrive in.
Live reservations for a product	For a single product, the shopper's reservation lines as the ERP records them, each showing the document number, date, quantity reserved and quantity still outstanding.	It needs a signed-in buyer and works on one product at a time. An empty table can mean either that nothing is reserved or that reservations were never set up for the client.
Product search results	Products found for the shopper's query, which is compared with each product's sku, barcode, title and title translations.	Use it only on the search results page, because the query is read from the URL; queries shorter than three characters are rejected.
Similar products	The other products belonging to the same product group as the current product, used for a suggestions area beneath it.	Out-of-stock items that the catalogue hides can still appear here, because this source applies the client's stock mode setting instead of the normal visibility option.
Live stock	How much of each product is available, returned by sku.	Expect the figure to move between requests: quantities sitting in other shoppers' carts are taken off the ERP count before it is returned.
Usual cart	A repeat-purchase list the platform derives for each customer account; no one curates it by hand.	Only signed-in shoppers get rows, and a shopper whose account yields no products sees an empty block without any error. A Buy again block on the account page is the typical use.
Products of a brand	All products carrying a given brand, for a brand page or for a shop-the-brand block on some other page.	Either pick the brand yourself in the block settings, or let the brand page's URL supply it.
Products of a collection	The members of one collection, a grouping the client creates for itself in addition to brands and categories.	The collection can be fixed while you configure the block or taken from the page address. Customer-specific promotions are left off these rows, so signed-in shoppers get only the general offer from this list, and their own pricing rules show up on the catalogue page instead.
Products by label	Whatever products the client has tagged with a chosen label, for example a top sales or new arrivals label.	Select the label from the list the client already has: the source looks labels up by name, and a typo quietly produces no products rather than an error.

Several catalogue sources are conditional: if the shop hides products from visitors who are not signed in, a guest sees nothing where such a block sits. A product block placed on a page that guests can open can therefore look broken even though nothing is wrong with the block. Check promoted products while you are signed in, because the rows depend on the buyer and a check made while signed out does not show what a customer receives.

Document sources

Platform orders stand apart: they are read from the platform's database rather than the ERP, which makes them available at every client. Each ERP-backed document source works only where the client's ERP provides the corresponding function. The ERP-backed document sources are personal: they answer for the signed-in buyer's own account. Place them on pages that require a login.

The ERP invoices, deliveries, orders, quotations, returns, tax invoices and consolidated invoices lists each require a start and an end date in YYYY-MM-DD form. Leaving either date out gets the request rejected, while any other date format is accepted but quietly answered with the ERP's fallback period instead of yours. Treat a not-found reply from the ERP invoices or returns list as an empty period, not as a fault. Normally the ERP invoice list arrives in pages, but some clients' ERPs cannot page it and return every invoice in the range at once, and a block has to cope with either response.

Source	What it provides	What to know
ERP orders	Orders placed by the signed-in buyer, read from the client's ERP for a chosen date range.	These are the buyer's own orders from the ERP, so a page that guests can open shows nothing here; place the block behind a login.
Platform orders	The platform's own record of orders submitted through the storefront, independent of the ERP.	Its period and paging parameters use different names from those of the ERP document lists. Expect people from the same company and branch to share one order list; it is not filtered per person. If the account has no linked ERP customer, the reply carries no body at all, so the block stays blank without any message.
ERP quotations	Offers the client has made to the buyer, held separately from orders because a quotation may never become one.	A block on a page that guests can open shows nothing, so place it behind a login.
ERP deliveries	Shipment records from the client's ERP for the buyer's orders, kept as a document type separate from the orders themselves.	A dedicated deliveries page that requires sign-in is the natural home for it.
ERP invoices	The shopper's billing history from the ERP for a chosen period, letting them check past charges.	Place it within the signed-in account area.
ERP tax invoices	Tax invoices only; the ERP keeps them apart from ordinary invoices, so the ERP invoices source never includes them.	Check that the client's ERP actually offers tax invoices, since having one invoice family says nothing about the other and a missing function leaves the block permanently empty.
ERP consolidated invoices	An ERP invoice that rolls several other documents into one; the ERP treats these as a separate family.	It is the least common of the standard ERP document families.
ERP returns	The shopper's returned goods as recorded in the ERP, a family separate from orders rather than part of them.	Give it a returns page that only signed-in shoppers can open.
Reservation orders	The shopper's reservation documents from the ERP, filtered to their account and a chosen period.	Don't assume the familiar header-and-lines layout: here the header comes back in the same reply as the attachments. If a client's ERP types its reservations differently, expect an empty list even when everything is working, because only one reservation document type is matched.
ERP documents (generic family)	A mixed list of documents from the ERP's single shared family, meant for clients whose ERP does not split documents into a family per type.	Besides the date range, it needs a third required value, an external identifier. The catalog entry warns that this identifier cannot be configured in the builder and that the storefront does not send it, so a block built on this family may reach nothing at all. Expect every matching document for the period in one reply; paging settings are ignored for this family alone.
Account ledger	The shopper's full account history of postings and its running balance, laid out in columns the client's administrator chose.	If you narrow it to a period, the totals and running balance still cover the whole ledger, so they will not match the rows shown; this is intended. A buyer with no postings receives a not-found answer.
Open items	An overview of what the shopper still has to pay: each open entry on the account plus one figure for the total owed.	Leave date filters off a block using this source: it ignores every parameter, so a filter would seem to work while the rows stay the same.
Client-defined document	A non-standard document set up by the client's administrator in their admin panel; you choose among the views they created, and each view decides its own columns.	According to its catalog entry, this class cannot be called yet, so a block set to it can come back empty until the supporting route ships. Where the administrator has declared a suitable view, a traceability call returns the delivery and return lines that came from the document, each with its delivery note and invoice, but it does not match them to individual order lines, and that pairing is not reliable yet.

How a document page is assembled

To lay out a document page, you combine a header block and an item lines block, each pointed at a different call of one document class, and a totals block that needs no source. Check availability for each of those blocks separately, since a client's ERP may answer the header call of a class and still lack its lines call. You never enter the document's id in these blocks; give the page a path with a dynamic id segment, and the page URL provides it.

In the Page Editor tab, the Documents group holds ERP Documents List, ERP document header, ERP document item lines, ERP document totals, Digitrade Documents List and Digitrade Document.

Documents that the client's administrator built appear first in the list, under their own heading, ahead of the standard documents that every client shares. Look for these by the names the client's administrator chose, which differ from client to client even for the same ERP document. When two entries look alike, read the second line beneath each one; it identifies the underlying class or ERP function.

Where each parameter's value comes from

Some source addresses include placeholders, such as a label name, that you fill in under the source parameters. For each placeholder you decide the value's origin: your own choice in the settings, the URL of the shopper's current page, or the data already loaded by the enclosing container block. A parameter with a single permitted origin simply states it, while one with several shows options with none selected, so you have to make the choice.

When you set the value yourself, you select it from what exists at this client, such as its labels, brands, collections, categories or document types, instead of typing it. A saved value that has since disappeared from the client's list is kept and flagged as not in the list, rather than cleared without warning. Leave any parameter unanswered and the block gets no address and shows nothing on the storefront, although saving the page still succeeds.

A product page works differently: only the outer container is given a source, and the blocks nested in it display pieces of the data it loaded without fetching anything themselves. Give a catalogue page's header and filter sidebar the filter source that matches its product list, such as filters of a category for catalog products; a mismatch raises no error, but the counts then refer to products the list is not showing. For a label-based list such as new arrivals or best sellers there is no matching filter source, so leave the header's filters source unset.

Sources that hold personal data

The personal-data marking tells you the source answers with one shopper's own information, such as their orders, invoices or recently viewed products. A personal source belongs only on a page where sign-in is required. If the page is left open to everyone, it is built for anonymous visitors, so even the signed-in buyer whose data it is sees an empty block and no error, while the rest of the page loads normally.

The Page Editor tab of a client page has a Yes or No choice for whether authorization is required to view the page content.

When a source is greyed out or missing

A greyed-out entry with a function name in brackets marks a source the platform offers but this client's ERP does not support. Keeping these entries visible lets you distinguish a gap at this client from a capability the platform lacks entirely. The remedy lies outside Site Builder: someone must declare the bracketed function in ERP Manager for the ERP system this client runs. That declaration takes effect at a client only after someone manually pushes the ERP data to that client.

Sources this client cannot use are collapsed into a single row showing how many there are, and expanding it lists them all. The source a block already points at is never collapsed into that row, so reopening an existing page after the client's ERP setup changes still shows its current choice. Retired, draft and removed-from-catalog badges are informational only; you can still select such a source, and pages that use a retired one continue to work.

A presentation built by the client's administrator can be missing from the list for reasons that are fixed elsewhere.

If the underlying ERP function has no parameter that limits results to the signed-in buyer, a list presentation never shows up in the builder, and no message explains its absence.
The builder offers a view only to blocks requesting the same kind of call as its role, so an item lines view never appears as the source of a page.
Functions left without a category are not offered in any select.
The builder shows each view under exactly the name the administrator typed, so one named after its ERP function displays a technical name.

When something is wrong, no more than one message shows beneath the source select, and its wording points you to the right person.

An unchecked-availability message means the client's backend did not respond, so every catalog source is listed and some may not actually work; wait and retry before configuring.
A catalog-unavailable message leaves live pages untouched because blocks keep their saved addresses; wait instead of changing the block.
A message that the catalog has nothing renderable for this block points to the block's own design, not to the client's setup.
A message that the source list is unavailable means loading the list failed; try again, and treat a repeat failure as a builder backend problem.

Templates, publishing and sync

Switching a block's template affects only its appearance, so when data goes wrong, investigate the chosen source and its parameters. Publishing stores your edits in the builder, and running Sync then rebuilds the static configuration the storefront is served from, so do both before expecting shoppers to see a change. The storefront can keep serving a cached copy even after both steps, so confirm the result on a storefront URL you haven't loaded before, not by reloading the one in front of you.

The Page Editor tab shows a Publish control, and the header offers Sync.

Data sources for page blocks