Skip to content

Cart & checkout

How a buyer's cart becomes per-seller purchase orders — the buy-box, pricing, shipping, and the cart pipeline.

The buy-box

When several sellers offer the same product, the storefront shows a buy-box: the winning offer drives the add-to-cart button, and an "Other sellers" widget lists the rest. Buyers can switch which seller's offer is in their cart.

Product page
   ├─ Buy-box: winning active offer  →  Add to cart
   └─ "Other sellers" widget: the runners-up  →  switch offer

The widget and pricing are per sales channel and only appear when marketplaceEnabled is on for that channel.

Price display modes

priceDisplayMode decides how seller offers interact with Shopware's native product price. Set it under Settings → Plugins → FlyokaiMarketplace → Marketplace.

Mode Product page & cart price "Other sellers" widget
marketplace (default) Buy-box winner's price overrides the native price. Seller offers.
hybrid Native price is kept. Seller offers plus a synthetic "Platform" offer at the native price.
native Shopware's native price only, never overridden. Seller offers only.

Use marketplace for a pure third-party marketplace, hybrid when the platform also sells the item itself, native when you want offers visible but the platform price to always lead.

Shipping

Multi-seller carts mean multiple shippers. marketplaceShippingMode picks how that's presented at checkout (modelled on the classic Unirgy Dropship behaviours):

Mode Buyer experience Total
aggregated (default) One cart-wide service tier picker (Standard / Expedited). Sum of each seller's carrier price for the chosen tier.
split One picker per seller, chosen independently. Sum of each seller's chosen service.

In split mode, shippingLabelMode controls what each per-seller dropdown shows:

  • service (default) — the marketplace tier name: "Standard — $5.99".
  • carrier — the underlying Shopware shipping method name: "UPS Ground — $5.99".

shippingLabelMode is ignored in aggregated mode (tier names are always shown).

How shipping resolves

Each seller defines shipping profiles → services (tiers) → carriers (a tier mapped to a Shopware shipping method with a price). At cart calculation the processor builds a shipping matrix — for every seller and every service tier, the carrier and price — and stores it on the cart for the Twig checkout to render.

seller's shipping profile
   service "Standard"  ──carrier──►  Shopware method "UPS Ground"  $5.99
   service "Expedited" ──carrier──►  Shopware method "UPS 2-Day"  $12.99

cart shipping matrix  =  { seller × service → (method, price) }

Operators manage global service tiers from Shipping admin; sellers map their carriers onto those tiers from the portal.

The cart pipeline

The plugin hooks Shopware's cart and order lifecycle at five points:

1. Add to cart
   BeforeLineItemAddedEvent → OfferAttacher
      resolves the winning offer (or an explicit offer id), stamps the line with
      seller_id · offer_id · commission_percent · unit_price

2. Switch offer (optional)
   OfferReplacer swaps the buyer's chosen seller offer in-cart

3. Cart calculation
   FlyokaiCartProcessor (runs after Shopware's DeliveryProcessor)
      groups lines into per-seller deliveries, computes the shipping matrix,
      stores shipping plans on the cart for checkout to render

4. Order placed
   CheckoutOrderPlacedEvent → OrderPlaced request
      materialises one purchase order per seller (flyokai_purchase_order[_line]),
      snapshotting offer, qty, unit price and commission onto each PO line

5. Delivery shipped
   order_delivery state → "shipped"
      advances the matching purchase order's status

Why the snapshot matters

Stages 1 and 4 snapshot the offer and commission onto the order. Once an order is placed, later edits to the product, the offer or the commission config never change what that order owed — which is exactly what makes statements reproducible and auditable.

Storefront surfaces

Path What
/products-offers/{productId} "Other sellers" widget — every active offer for a product.
/seller/{slug} Seller microsite — branding + the seller's catalogue.
/catalog/products/search Store-API product search with marketplace seller context.