Template Tags: Checking Out

You can view a tutorial on checking out here.

Checkout Tags

  • checkout_form The final step in the transaction
  • gateway_fields_url Returns an action URL for dynamically fetching gateway fields from an AJAX call
  • submitted_order_info Outputs information about the order (success or failure) order ids for successful orders and error messages or failed orders


Whether you use multi-page checkouts,or a single page the way you structure your cart is unimportant to CartThrob for the most part. There are only a few key things to keep in mind about this process however.

  1. Checkout is the last step in your cart process.
  2. Credit Card Numbers are not stored in session. If you plan to process credit cards on your site, the credit card number should be captured during the last step, also known as "checkout."

Checkout is a step in the cart process that completes the customer's purchase and begins processing of payments. Among other things, checkout does the following:

  • validates fields required by the payment gateway
  • creates an order entry in the orders channel
  • creates a new member (if you are capturing registration information)
  • sends data to the payment gateway (if any) and handles other required gateway integration
  • runs extensions attached to the checkout process (if any)

The checkout is not specifically tied to payments, it's primary purpose is pushing data into ExpressionEngine and attempting to complete the transaction. It's the point where customer information is captured, manipulated, stored, and passed on to a merchant account or payment processor (if you are using one). Except for validation and payment errors, it's the last step in the ordering process.

Handling Errors

  • Validation Errors: All validation errors (missing customer fields, badly formatted fields, or captcha errors) are reported using the standard ExpressionEngine error template.
  • Payment Gateway Errors: All payment gateway errors can be displayed using the submitted_order_info tag tag. Using this tag, you can output gateway errors and provide your customer information about how to correct these errors.

Every time a customer attempts a checkout an order is created in the orders channel. Configuring the system to attach different statuses to each order is important in identifying completed and failed orders. Check the cartthrob > order settings page to configure order statuses.

It is always a good idea to familiarize yourself with documentation provided by your Merchant Account provider. Understanding the types of errors that your customer might see is always useful. Ask your gateway provider for a list of error conditions and keep them on file as a reference.

Order Complete

Use the submitted_order_info tag to display messages about both successful as well as failed orders. Generallly after the order is complete you should show your customer a message that announces the order success, and gives them additional information about their completed order. It's common to provide full order details, a link to an account page, or other information recapping the recently completed order.