Guides

ICheckoutManagerBase (Checkout)

CheckoutManagers are used to manage the most aspects of the checkout workflow. Merchello's default CheckoutManager is the BasketCheckoutManager which is intended to be used for basket checkout outs.

🚧

CheckoutManager supersede the SalePreparation in earlier versions.

Prior to Merchello 1.14.0, the SalePreparation class was used to manage the checkout workflow.

The CheckoutManager breaks down the checkout workflow into several logical areas which can be seen in the ICheckoutManagerBase interface. Each area is managed by a specific lazy loaded area checkout manager.

/// <summary>
    /// Defines the base checkout workflow.
    /// </summary>
    public interface ICheckoutManagerBase : ICheckoutContextManagerBase
    {
        /// <summary>
        /// Gets the checkout manager for customer information.
        /// </summary>
        ICheckoutCustomerManager Customer { get; }

        /// <summary>
        /// Gets the checkout extended manager for custom invoicing.
        /// </summary>
        ICheckoutExtendedManager Extended { get; }

        /// <summary>
        /// Gets the checkout manager for marketing offers.
        /// </summary>
        ICheckoutOfferManager Offer { get; }

        /// <summary>
        /// Gets the checkout manager for shipping.
        /// </summary>
        ICheckoutShippingManager Shipping { get; }

        /// <summary>
        /// Gets the payment.
        /// </summary>
        ICheckoutPaymentManager Payment { get; }
    }

Contextual information is shared between the managers via a CheckoutContext .

// IBasket extension method
var checkoutManager = CurrentCustomer.Basket().GetCheckoutManager([optional settings]);

ICheckoutCustomerManager

ICheckoutCustomerManager(s) are responsible for temporarily saving and retrieving previously saved customer information during the course of a checkout workflow.

// ICheckoutCustomerManager of type BasketCheckoutCustomerManager
var customerManager = CurrentCustomer.Basket().GetCheckoutManager().Customer;
NameDescription
SaveBillToAddress(IAddress billToAddress)Saves the bill to address
SaveShipToAddress(IAddress shipToAddress)Saves the ship to address
IAddress GetBillToAddress()Gets the bill to address
IAddress GetShipToAddress()Gets the bill to address
CheckoutContext.ChangeSettings.ResetCustomerManagerDataOnVersionChange = true;

📘

Default context behavior for BasketCheckoutCustomerManager

When the CheckoutContext resets to a new version, the default behavior for the BasketCheckoutCustomerManager is to purge any previously saved billing and shipping addresses.

ICheckoutExtendedManager

ICheckoutExtendedManager(s) are responsible for handling optional bits of a checkout workflow, such as adding custom line items and adding notes to an invoice.

var checkoutExtendedManager = CurrentCustomer.Basket().GetCheckoutManager([optional settings]).Extended;
NameDescription
AddItem(ILineItem lineItem)Adds a to the collection of items. Intended for custom line item types.
RemoveItem(ILineItem lineItem)Removes a line item from the collection of items. The line item to be removed.
ClearNotes()Clears all notes
SaveNotes(IEnumerable messages)Saves a list of messages for creating individual invoice notes
AddNote(string message)Adds to get associated with the invoice as a note on invoice creation.
IEnumerable GetNotes()Gets any previously added notes.
CheckoutContext.ChangeSettings.ResetExtendedManagerDataOnVersionChange = true;

📘

Default context behavior for BasketCheckoutExtendedManager

When the CheckoutContext resets to a new version, the default behavior for the BasketCheckoutExtendedManager is to purge any previously saved notes.

ICheckoutOfferManager

ICheckoutOfferManager(s) are responsible for temporarily saving, retrieving and applying marketing offers, coupon offers by default, respective to a sale during the course of a checkout workflow.

var checkoutOfferManager = CurrentCustomer.Basket().GetCheckoutManager([optional settings]).Offer;
NameDescription
OfferCodesGets the collection of previously saved offer codes.
RemoveOfferCode(string offerCode)Removes an offer code from the OfferCodes collection.
ClearOfferCodes()Clears the offer codes collection
RedeemCouponOffer(string offerCode)Attempts to redeem an offer to the sale. Returns IOfferRedemptionResult where a successful result containing a discount line item.
CheckoutContext.ChangeSettings.ResetOfferManagerDataOnVersionChange = true;

📘

Default context behavior for BasketCheckoutOfferManager

When the CheckoutContext resets to a new version, the default behavior for the BasketCheckoutOfferManager is to purge any previously saved offer codes.

ICheckoutShippingManager

ICheckoutShippingManager(s) are responsible for saving and retrieving shipping rate quotes during the course of a checkout workflow.

var checkoutShippingManager = CurrentCustomer.Basket().GetCheckoutManager([optional settings]).Shipping;
NameDescription
SaveShipmentRateQuote(IShipmentRateQuote approvedShipmentRateQuote)Saves a IShipmentRateQuote as a shipment line item
SaveShipmentRateQuote(IEnumerable approvedShipmentRateQuotes)Saves a collection of IShipmentRateQuotes as shipment line items
ClearShipmentRateQuotes()Clears all IShipmentRateQuotes previously saved
CheckoutContext.ChangeSettings.ResetShippingManagerDataOnVersionChange = true;

📘

Default context behavior for BasketCheckoutShippingManager

When the CheckoutContext resets to a new version, the default behavior for the BasketCheckoutShippingManager is to purge any previously saved shipping rate quotes.

ICheckoutPaymentManager

ICheckoutShippingManager(s) are responsible for saving and retrieving payment methods during the course of a checkout workflow.

NameDescription
IsReadyToInvoice()True/false indicating whether or not the ICheckoutPaymentManager is ready to prepare an IInvoice
PrepareInvoice()Generates an IInvoice
PrepareInvoice(IBuilderChain invoiceBuilder)Generates an IInvoice representing the bill for the current "checkout order"
ClearPaymentMethod()Removes a previously saved payment method
SavePaymentMethod(IPaymentMethod paymentMethod)Saves a IPaymentMethod
GetPaymentGatewayMethods()Gets a list of all possible Payment Methods
GetPaymentMethod()Gets the previously saved IPaymentMethod
AuthorizePayment(IPaymentGatewayMethod paymentGatewayMethod, ProcessorArgumentCollection args)Attempts to process a payment
AuthorizePayment(IPaymentGatewayMethod paymentGatewayMethod)Attempts to process a payment
AuthorizePayment(Guid paymentMethodKey, ProcessorArgumentCollection args)Attempts to process a payment
AuthorizePayment(Guid paymentMethodKey)Attempts to process a payment
AuthorizeCapturePayment(IPaymentGatewayMethod paymentGatewayMethod, ProcessorArgumentCollection args)Attempts to Authorize and Capture a Payment
AuthorizeCapturePayment(IPaymentGatewayMethod paymentGatewayMethod)Attempts to Authorize and Capture a Payment
AuthorizeCapturePayment(Guid paymentMethodKey, ProcessorArgumentCollection args)Attempts to Authorize and Capture a Payment
AuthorizeCapturePayment(Guid paymentMethodKey)Attempts to Authorize and Capture a Payment
CheckoutContext.ChangeSettings.ResetPaymentManagerDataOnVersionChange = true;

📘

Default context behavior for BasketCheckoutPaymentManager

When the CheckoutContext resets to a new version, the default behavior for the BasketCheckoutPaymentManager is to purge any previously saved payment methods.

Replacing the default CheckoutManager(s)

Developers can write their own area managers to augment the default behavior and provide additional application specific functionality by implementing the following

Checkout areaBase class
CustomerCheckoutCustomerManagerBase
ExtendedCheckoutExtendedManagerBase
OfferCheckoutOfferManagerBase
PaymentCheckoutPaymentManagerBase
ShippingCheckoutShippingManagerBase

After you've created your class, you can then modify the type reference in the Merchello.config

<pluggable>
    <object alias="CustomerContext" type="Merchello.Web.CustomerContext, Merchello.Web" />
    <object alias="BasketCheckoutCustomerManager" type="Merchello.Web.Workflow.Checkout.BasketCheckoutCustomerManager, Merchello.Web" />
    <object alias="BasketCheckoutOfferManager" type="Merchello.Web.Workflow.Checkout.BasketCheckoutOfferManager, Merchello.Web" />
    <object alias="BasketCheckoutShippingManager" type="Merchello.Web.Workflow.Checkout.BasketCheckoutShippingManager, Merchello.Web" />
    <object alias="BasketCheckoutExtendedManager" type="Merchello.Web.Workflow.Checkout.BasketCheckoutExtendedManager, Merchello.Web" />
    <object alias="BasketCheckoutPaymentManager" type="Merchello.Web.Workflow.Checkout.BasketCheckoutPaymentManager, Merchello.Web" />
  </pluggable>