Use the Sitegenerator standard cart

Use this quickstart when a Sitegenerator shop needs one server-owned purchase flow for consumers, verified business buyers, and quote-only business leads. After setup, cart totals, tax, shipping, checkout eligibility, quotes, and orders all use the Public Storefront contract.

Start with the generated cart page

New Sitegenerator projects contain /cart for English and /warenkorb for German. The page includes shop/standard-cart.html and loads the standard cart controller. The controller covers line changes, coupons, separate billing and shipping addresses, shipping, legal declarations, payment selection, order placement, quote requests, the PayPal handoff and recovery, and public order status.

Configure product logistics with a valid fulfillment strategy for every physical variant. Without that configuration, the server returns the product_fulfillment_unavailable eligibility blocker and does not allow a direct order. A quote request can remain available.

Add a product action with public variant data:

html
<button
  data-nucleus-add-to-cart
  data-variant-id="VARIANT_UUID"
  data-quantity="1"
  data-unit-of-measure="PC"
>
  Add to cart
</button>

On a product page, the shop logic creates a cart when needed, adds the variant, and then opens /cart. When the action is already on the cart page, the same controller renders the complete cart response directly. Use data-nucleus-cart-url to select a different cart route or data-nucleus-cart-navigation="none" to stay on the current page. The browser never derives a tax jurisdiction, rate, tax amount, discount, or shipping total. When the server hides prices or requires a review, the cart does not show cached or calculated amounts.

Before adding an item, the module reloads the server cart and company context. It replaces a missing or completed cart only through the server recovery contract. If the completed cart still has a pending payment, that payment is preserved: the module opens the cart for recovery and does not append an item to the completed cart. Integrations can observe nucleus-standard-cart-item-added, nucleus-standard-cart-recovery-required, and nucleus-standard-cart-error.

For a published individual unit, the cart hold binds the selected serial identity. Order placement reuses that authorized hold. It must not substitute another unit of the same variant or treat another cart's reservation as its own. If the hold is no longer valid, order placement stops and the shop reloads the cart and availability.

The sliding reservation may be renewed, but an individual-unit hold ends no later than two hours after it was first created. A cart can hold at most three active individual units. Treat UNIT_UNAVAILABLE as a neutral availability result and do not automatically retry ERR_RATE_LIMIT.

Recovery resumes only an order or payment flow that was already created. It does not repair a failed placement or restore missing or drifted authority between the individual unit, reservation, and order line. Reload cart and eligibility instead of retrying placement through recovery.

Keep B2C and B2B paths separate

A consumer or guest sends billing and shipping addresses to POST /storefront/checkout/prepare. The server rebuilds the tax facts, reprices the cart, and returns a new pricing revision.

A verified business buyer first selects a company returned by GET /account/companies. Only buyer and administrator roles can use that context. The standard cart then offers the approved company billing and shipping addresses. A company name or an unverified VAT ID does not activate B2B tax treatment.

The initial EU pilot applies cross-border goods and general B2B service treatment only when the current evidence matches the determined customer country. Multi-establishment and triangular-transaction cases need dedicated presence and policy modules; do not unlock them in the browser by choosing a different VAT ID.

An unverified business lead can request a quote when the storefront allows it. Direct ordering remains unavailable until the server has validated the company and bound the buyer to it.

Keep market, delivery, billing, and tax countries separate

The storefront context exposes the sales-channel market country separately from the delivery countries for physical direct checkout. The market country selects country-scoped prices. The shipping destination controls delivery and shipping charges. The billing country remains an independent address fact, while the server determines the tax place from the supply type, buyer status, and the relevant addresses.

Countries and regional groups enabled on the commerce profile are the standard delivery countries. When neither countries nor regional groups are configured, the policy remains unrestricted. A configured scope that no longer resolves to any country fails closed. An allowed country does not guarantee checkout: a matching delivery zone and shipping method, inventory, and tax readiness are still required.

Physical and mixed carts are checked against the shipping destination. A digital-only cart is not delivery-gated. When a physical destination is not enabled, or a cross-border direct checkout lacks a Tax V3 decision, the standard cart keeps the quote path available instead of deriving its own country rule.

The default shipping destination uses the market country when that country is enabled. Otherwise, the server uses the first country in the sorted delivery country list. The commerce profile's default buyer country remains independent and is not used as a shipping default.

GET /storefront/context includes the relevant server contract:

json
{
  "marketCountryCode": "DE",
  "directCheckoutCountryPolicy": {
    "mode": "restricted",
    "appliesTo": "shipping_destination",
    "defaultDestinationCountryCode": "DE",
    "allowedDestinationCountryCodes": ["AT", "DE"]
  }
}

Respect pricing revisions

Use the pricing revision returned by the current cart in the quote request and the revision returned by checkout eligibility in the place-order request. Reload cart and eligibility after an address, company, quantity, coupon, shipping, or payment-context change. If the server reports a stale tax quote or a changed total, show the new amount and require confirmation.

The quote created from a cart stores the current commercial and tax snapshot. Before quote-to-order conversion, Workspace determines tax again. A material change requires reconfirmation; an accepted order, invoice, and accounting projection keep the immutable order tax snapshot.

If a connection fails after submission, retrying the same cart and pricing revision returns the same quote. The server does not create a second quote or duplicate the internal request context.

For released individual-unit offers, use GET /public/v1/storefront/individual-unit-listings?variantId=<UUID> to filter by variant before the server applies its 24-item limit. The standard-cart client exposes this as client.loadIndividualUnitListings(variantId); without an argument it requests the global list. Empty, invalid, nil, or repeated filter values return HTTP 400 with INVALID_VARIANT_ID. Unknown, foreign, or hidden variants return an empty list in the current buyer context. Adding a unit still requires the concrete listingId and offerRevision returned for the selected offer.

An individual-unit cart line exposes its bound public title, condition, and released images in individualUnit. Render that snapshot instead of the generic variant name so the buyer can recognize the exact selected unit.

When the cart contains an individual unit, quote creation releases its short cart hold. Converting the accepted quote must reacquire that exact unit. If it is no longer available, Workspace must not substitute another unit of the same variant or create an order with an incomplete reservation.

Workspace also validates current product logistics before converting an accepted quote into an order. Every physical line needs a valid fulfillment strategy. The order stores that strategy as its line snapshot, so later product changes do not rewrite an existing order. If direct cart conversion returns CART_FULFILLMENT_UNAVAILABLE, reload eligibility and have the physical variants' product logistics corrected before starting payment.

Extend the reference flow safely

Verify every standard-cart extension for consumers, verified business buyers, and business leads that are not yet verified. Cover order placement and quote requests, and reload the authoritative server state after every change to an address, company, quantity, coupon, shipping method, or payment method.