Skip to main content

Checkout & totals

The deposit / balance split has to render correctly in five different places: cart, checkout summary, order confirmation, invoice, and credit memo. The module's totals collectors and KO templates cover all five.

The totals collectors​

Three totals collectors, registered in etc/sales.xml:

CollectorStageFile
Pre-order fee (quote)Cart, checkout, summaryModel/Total/Quote/PreorderFee.php
Pre-order fee (invoice)Invoice renderingModel/Total/Invoice/PreorderFee.php
Pre-order fee (credit memo)Credit memo renderingModel/Total/Creditmemo/PreorderFee.php

All three share the same calculation — they compute the deposit (what the customer pays now) and split it from the deferred balance. The collector outputs:

  • A new negative-adjustment line that brings the order total down to the deposit amount.
  • A separate balance-owed annotation rendered in summary panels and the order confirmation.

Cart layout​

view/frontend/layout/checkout_cart_index.xml adds the pre-order fee KO renderer to the cart totals block. Customers see:

Subtotal           €450.00
Shipping            €10.00
Tax                 €92.00
Pre-order deposit  −€414.50
─────────────────────────
Total              €137.50
Balance owed       €414.50

The negative line is what makes the order total resolve to "deposit only" without breaking Magento's standard tax / shipping math.

Checkout summary​

view/frontend/layout/checkout_index_index.xml adds the same KO renderer to the checkout summary. The customer sees the same breakdown plus a small explanatory tooltip ("This deposit secures your pre-order. The balance will be charged on shipment.").

Order confirmation email + admin order view​

The pre-order fee is rendered as a normal order line via Magento's standard total-block rendering, so no extra layout work is needed for the confirmation email or the admin order screen — the same totals collector runs and the same lines render.

Invoice & credit memo​

When the merchant invoices the deposit, the invoice totals collector (Model/Total/Invoice/PreorderFee.php) reproduces the same split. Tax is owed in full on the deposit invoice — see Payments configuration → Tax handling.

When the customer cancels and the merchant issues a credit memo, the credit-memo collector reverses the deposit line and (if configured) the deposit amount itself.

Currency conversion​

When the customer switches display currency mid-cart, Observer/RecalculatePreorderOnCurrencyChange.php listens for the currency-switch event and refreshes the deposit calculations in the resolved currency. So a US customer browsing in USD sees the deposit in USD even if the base store is EUR.

PayPal Express edge cases​

PayPal Express bypasses the standard checkout total collection in some flows — the express button creates the order before checkout summary is rendered. Two pieces handle this:

  • Observer/PaypalExpressPlaceOrder.php — re-resolves the pre-order fee when PayPal Express fires paypal_express_place_order so the right amount is charged.
  • Plugin/Paypal/Model/Api/NvpPlugin.php — adjusts the NVP request to PayPal so the cart total they show matches the deposit, not the full price.

Without these, PayPal Express would charge the full product price instead of the deposit. With them, deposit-mode pre-orders work cleanly through the express button.

Quote-to-order transfer​

The quote item carries a preorder_id column (added in db_schema.xml). Plugin/Quote/Item/ToOrderItem.php copies it onto the order item at order placement, so the post-placement observer (CreatePreorderAfterOrderPlace) has the link it needs to attach the order to the pre-order entity.