When you’re building checkout flows, it’s easy to think of everything as happening in one place, but in reality, a POS is always juggling multiple entities at once. A cashier might be scrolling through a product list, opening a past order, or managing the cart in front of a customer, and all of these need to work together without conflict.
To make this possible, Builder keeps track of two perspectives at all times:
What the user is currently looking at or selecting.
What’s actually active in the cart and driving the checkout.
This dual model is what ensures that your flows behave predictably. Once you understand this split, the rest of Builder’s structure makes sense: sections know which data to show, actions know which entities to update, and your checkout flows can mix browsing, selecting, and selling without stepping on each other.
Builder organizes everything you do around two groups of entities:
Selected items
The last item selected in a list or grid element (e.g., a product grid, product list, customer list, or order list)
Active context
The ongoing cart, including the active order, its products, and the customer attached to it.
This structure defines how sections display data, how actions are applied, and how logic runs in your flows.
Selected means “the most recently clicked or highlighted item in a list or grid.”
Active means “the entity tied to the ongoing cart.”
These may match, but not always.
For Example:
Selecting a customer from the customer list makes them the selected customer.
Adding that customer to the cart also makes them the active customer.
But if you select a different customer without adding them to the cart, the selected and active customers will be different.
The distinction between selected items and the active context isn’t just theoretical, it directly shapes how your flows behave. It determines both:
Which Dynamic Data is displayed (what sections on screen show).
Which entities your actions affect (where notes, discounts, or updates get saved in the database).
Here’s how this plays out in real use:
In actions:
Adding an order note → saved to the active order.
Adding a customer note → saved to the selected customer.
Adding a product discount → applied to the selected product in a list or cart.
Scanning a product (without using the search field) → added to the active cart, and also becomes the selected product.
Selecting a different customer without adding them to the cart → that person becomes the selected customer, while the active customer in the cart does not change.
In section elements:
List/Grid sections → show dynamic data for the selected item in that list.
Cart sections → show dynamic data for the active context (the current cart, its order, products, and customer).
