The Theme API in Shopp allows you to add arbitrary fields to collect inputs from customers during checkout.

Adding Custom Checkout Inputs

Adding Custom Checkout Inputs

The design of Shopp as a good plugin citizen in the WordPress environment is based on a principle of good separation of roles. Generally speaking, plugins shouldn’t know or care about how things on the front-end look, only how they work. Some plugins marry the look and feel displayed to customers to settings and controls in the plugin. This is a nice way to give control over how the front end looks and works to non-programmers, but it also boxes programmers in.

In Shopp, part of the look, the interface (such as the checkout form), is laid out by templates using Theme API calls. This allows a developer full control over the look and feel without needing to undo any boxed in plugin layout.

Getting Setup

Before you can begin modifying your checkout form, you will need to setup custom Shopp content templates in your active WordPress theme. The Shopp User Guide has details for setting up custom templates properly.

Your custom edits will take place in the checkout.php template file, located in your active WordPress theme’s file structure under a shopp/ subdirectory.

Adding a Simple Comments Box

To add a text field for taking customer comments, use the following:

<?php shopp('checkout.order-data', 'name=Comments&type=textarea'); ?>

That will add an HTML <textarea> box for customers to enter a message that will be attached to their order. You can add as many as you need, and the shopp('checkout.order-data') tag supports a variety of input types including: text, password fields, select drop-down menus, checkboxes and more. You can refer to the API reference guide for the shopp('checkout.order-data') tag for all of the supported options for each of the field types.

The default receipt.php template file that is part of the Shopp template starter kit installed into your theme already has code that will show the custom fields and the information the customer provided on the customer’s receipt at the end of their order and in their order email notification:

<?php if( shopp('purchase','has-data') ): ?>
    <?php while( shopp('purchase','orderdata') ): ?>
        <?php if ( '' == shopp('purchase','get-data') ) continue; ?>
        <li><strong><?php shopp('purchase','data','name'); ?>:</strong> <?php shopp('purchase','data'); ?></li>
    <?php endwhile; ?>
<?php endif; ?>

Custom order data inputs will automatically be viewable in the order receipt when accessing an order through the admin.

Making Required Fields

By using the required option, you can make Shopp’s checkout scripting require an input to be filled out before proceeding. For example, you might want to require that someone agree to “Terms of Service” before purchasing a service.

Adding the required=true option, Shopp will add a required class to the input, and provided that Shopp’s behavior scripts are properly loaded, it will validate that the field is not left empty (or unmarked for checkboxes) when the checkout form is submitted. If the field is empty, an error alert will be displayed, or an error class will be activated on the field to provide configurable visual feedback about the missing field.

<?php shopp('checkout.order-data','type=checkbox&value=on&name=terms&required=true'); ?> You must agree to the <a href="">Terms of Service</a>.

You can take it further by also adding backend validation using the shopp_validate_checkout filter hook. In cases where Javascript validation is unavailable, broken or the user has disabled it in their browser, backend validation is the last line of defense for ensuring required fields are valid and required before allowing the checkout to continue.

For this example, you can use the filter in your theme’s functions.php file to make sure that your field is filled out, even if the Javascript validation fails.

function my_validation() {
    if ( empty($_POST['data']['terms']) ) {
        // Add an error to the list of errors
        new ShoppError('You must agree to the terms of service to proceed.',false,SHOPP_ERR);
        return false;
    return true;

You can find out more about the shopp_validate_checkout filter hook in the API reference guide.

Using a Click Wrap Field

A better way to include a field that requires users to agree to a terms before checkout is with a click wrap field. The click wrap field is a specially designed field set that displays the terms in a scrollable frame with a required checkbox below it. The text of the terms can be provided directly, or a WordPress page can be specified that includes the fully stylized text of the terms.

shopp('checkout', 'clickwrap','agreement=terms-and-conditions');

In the example above, a click wrap field is added with terms from a WordPress page identified with the slug terms-and-conditions.

Find more on the click wrap field in the API reference guide.


Shopp has a flexible system allowing any field to be added to the checkout form. Custom checkout fields are great tools for gathering special information like gift messages, referral sources and even get customers to agree to purchase terms before they can complete their order.


Jonathan was born at an early age and began designing and developing shortly after. He is the founder of Ingenesis Limited and Project Lead on the Shopp e-commerce plugin for WordPress. He lives and works in the heart of the midwest US with his family. He fancies himself a designer of code, and is only slightly addicted to coffee.

You must be logged in to post a comment.

© Ingenesis Limited. Shopp™ is a registered trademark of Ingenesis Limited.