Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Final order processing

Final order processing

The final order processing during the checkout process is implemented by the CheckoutService. To perform a checkout, the CheckoutService requires a ShoppingCart and an OrderPayment. The ShoppingCart essentially represents an order for products, complete with the customer and shipping information. The OrderPayment provides information about how the customer will pay for the items in the cart. CheckoutService.checkout() is invoked with these two parameters and will throw an exception if anything goes wrong. The exception may be an EpServiceException, or any of the standard exceptions thrown by implementors of the PaymentGateway interface (see Payment Processing).

The main responsibility of the checkout operation is to process the payment and persist the order. It is assumed that customer and product information can be changed at any time; therefore, all information about the order, product, customer, and payment must be stored as copies in separate database tables.

The final order processing can be broken down into three subgroups of actions which occur after the customer confirms his/her purchase in the storefront checkout (see the abstractCheckoutServiceDelegate bean in the core project's service.xml file):

  1. Setup actions (setupActionList).
  2. Reversible actions (reversibleActionList).
  3. Finalize actions (finalizeActionList).
            <html><body>
<pre class="j-path">core<span class="j-pathsep">/</span>ep-core<span class="j-pathsep">/</span>src<span class="j-pathsep">/</span>main<span class="j-pathsep">/</span>resources<span class="j-pathsep">/</span>spring<span class="j-pathsep">/</span>service<span class="j-pathsep">/</span>service.xml</pre>
<pre class="j-text"><code>&lt;bean id="abstractCheckoutServiceDelegate" abstract="true" class="com.elasticpath.service.shoppingcart.impl.CheckoutServiceImpl"&gt;
	&lt;property name="shippingServiceLevelService" ref="shippingServiceLevelService"/commerce-legacy/&gt;

	&lt;property name="setupActionList"&gt;
		&lt;list&gt;
			&lt;ref bean="preCheckoutCheckoutAction" /&gt;
			&lt;ref bean="shippingInformationCheckoutAction" /&gt;
			&lt;ref bean="giftCertificateBalanceCheckerCheckoutAction" /&gt;
			&lt;ref bean="stockCheckerCheckoutAction" /&gt;
			&lt;ref bean="updateCustomerCheckoutAction" /&gt;
		&lt;/list&gt;
 	&lt;/property&gt;

	&lt;property name="reversibleActionList" ref="reversibleActions"/commerce-legacy/&gt;

	&lt;property name="finalizeActionList"&gt;
		&lt;list&gt;
			&lt;ref bean="clearShoppingCartCheckoutAction" /&gt;
			&lt;ref bean="postCheckoutCheckoutAction" /&gt;
			&lt;ref bean="sendNotificationEmailCheckoutAction" /&gt;
		&lt;/list&gt;
	&lt;/property&gt;
&lt;/bean&gt;

&lt;util:list id="reversibleActions" list-class="java.util.ArrayList"&gt;
	&lt;ref bean="createNewOrderCheckoutAction" /&gt;
	&lt;ref bean="populateOrderDataCheckoutAction" /&gt;
	&lt;ref bean="createGiftCertificatesCheckoutAction" /&gt;
	&lt;ref bean="populateTemplateOrderPaymentCheckoutAction" /&gt;
	&lt;ref bean="processOrderPaymentsCheckoutAction" /&gt;
	&lt;ref bean="updateLimitedUsageNumbersCheckoutAction" /&gt;
	&lt;ref bean="subscriptionCreditCheckCheckoutAction" /&gt;
	&lt;ref bean="updateOrderCheckoutAction" /&gt;
	&lt;ref bean="processCouponCustomerAssignmentsCheckoutAction" /&gt;
&lt;/util:list&gt;</code></pre>
</body></html>

This service.xml file can be modified to refer to your custom implementations of the CheckoutAction interface.

Processing Steps

Each step corresponds to one of the beans listed above.

  1. Verify inventory (stockCheckerCheckoutAction).
  2. Update customer (updateCustomerCheckoutAction).
  3. Create new order (createNewOrderCheckoutAction).
  4. Create purchased gift certificates (createGiftCertificatesCheckoutAction).
  5. Populate OrderPayment template object (populateTemplateOrderPaymentCheckoutAction).
  6. Process payments (processOrderPaymentsCheckoutAction).
  7. Update usage counts on limited-use coupons and promotions (updateLimitedUsageNumbersCheckoutAction).
  8. Conduct credit check for recurring charge items (subscriptionCreditCheckCheckoutAction).
  9. Persist order to database (updateOrderCheckoutAction).
  10. Assign promotion coupons to customer (processCouponCustomerAssignmentsCheckoutAction).
  11. Clear shopping cart (clearShoppingCartCheckoutAction).
  12. Send order confirmation e-mail (sendNotificationEmailCheckoutAction).
Note: Note:

preCheckoutCheckoutAction and postCheckoutCheckoutAction do nothing in the OOTB source code.

The CheckoutAction implementations of each step delegate to the following key classes and files:

Key classes and files

  • BillingAndReviewControllerImpl - Spring MVC controller for the final checkout step.
  • CheckoutService - Service that executes a checkout when requested by the BillingAndReviewControllerImpl.
  • CheckoutEventHandler - Interface implemented by a class wired via Spring to the CheckoutService so that it can be notified of events during the checkout execution. This is useful for extending or modifying checkout functionality.
  • ShoppingCart - The shopping cart contains items to be purchased during a checkout.
  • OrderPayment - An order payment represents information about how the customer will pay for the order.
  • PaymentGateway - Interface implemented by payment gateways that handle financial transactions such as credit card or PayPal payments.
  • Order - Represents a completed order for products.
  • OrderSku - A snapshot of information about a purchased SKU at the time of checkout.
  • OrderShipment - Contains shipping information for an order.
  • Inventory - Contains inventory information for a particular product SKU.
  • OrderAddress - A snapshot of the customer's address (billing and shipping) at the time of checkout.

Click the thumbnail below to view the relationships between key classes involved in the checkout and order creation process.

CheckoutClassDiagram.gif

The CheckoutEventHandler

The CheckoutService Spring configuration injects a CheckoutEventHandler instance into the Service, which provides hooks into the checkout process at certain points. By creating a new class implementing the CheckoutEventHandler interface and wiring in the new class via the Spring configuration, one can easily extend the Checkout Process at certain steps to call custom methods. Three extensible points exist: preCheckout, postCheckout, and preCheckoutOrderPersist (called just before the newly-created Order is persisted).

For example, if you wanted to have some code that called a webservice in some other application every time a checkout was completed, you could write a new class extending the CheckoutEventHandler and put the code in that class' postCheckout() method. Then you would edit the Spring bean definition for the CheckoutService to inject your new class into the Service, and your code would automatically be called at the right time.

Important concepts

Transactions

The checkout service is configured in Spring so that the checkout method does NOT run as a transaction. This is because we don't want to trigger transaction overhead while processing credit card payments. If the credit card payment is successful, checkout calls processOrder(), which does run as a transaction and handles the creation and storage of the order information. Transactions are configured on a per-method basis in the service.xml Spring configuration file.

Status Objects

Orders, OrderPayments, and OrderShipments all have Status fields: OrderStatus, OrderPaymentStatus, and OrderShipmentStatus respectively.

The current OrderStatus values are:

  • IN_PROGRESS
  • PARTIALLY_SHIPPED
  • COMPLETED
  • ONHOLD
  • CANCELLED
  • AWAITING_EXCHANGE
  • FAILED

The current OrderPaymentStatus values are:

  • APPROVED
  • PENDING
  • FAILED

The current OrderShipmentStatus values are:

  • AWAITING_INVENTORY
  • INVENTORY_ASSIGNED
  • RELEASED
  • SHIPPED
  • ONHOLD
  • CANCELLED
  • FAILED_ORDER

Creating an Order

The CheckoutService creates an Order object and passes it to the OrderService to persist.

Every Order must have a unique OrderNumber, set at Order creation time (not at persist time). Unique order numbers are obtained from the OrderService.getNextOrderNumber() method.

OrderService

The OrderService provides services to query on Orders and persist Orders, but not to generate Orders. Order generation is performed by the CheckoutService.

There are methods to search for orders by various basic criteria, or you can pass in an OrderSearchCriteria object. The search methods must translate the given criteria into a Criteria String for the Persistence engine, and they do so via an OrderCriterion factory class.

Data replication

At order time a snapshot of various objects must be created and stored in separate tables to insulate the Order details from any future changes in prices, inventory, addresses, etc. Objects are copied as follows:

ProductSku --> OrderSku BillingAddress --> OrderAddress (for the Order) ShippingAddress --> OrderAddress (for the OrderShipment)

Attributes such as shipping cost, quantity, taxes, etc. are calculated at Order time and frozen in the appropriate object (Order, OrderShipment, OrderSku, etc).

Failed Orders

Failed orders are saved to the database (TORDER table) with the order's STATUS set to FAILED. The Quartz job, cleanupFailedOrdersJob, will eventually remove the failed order from your system.