Table of Contents

Custom Checkout Fields

Important: Requires v0.2.4 or higher. Set your version in your store settings.

Overview

Sometimes it is necessary or desirable to include additional input fields on checkout, such as:

It's (relatively) easy to add custom fields to your FoxyCart checkout page, providing you know some HTML. In a nutshell, any code you insert in between the tags ^^custom_begin^^ and ^^custom_end^^ will be inserted in your checkout page, in between a container div#fc_custom_fields_container.

An Example

Here's a basic example of the above functionality. It doesn't matter where you put this code. It will be moved into the checkout form when FoxyCart loads your checkout page, so it can be after the </body> or </html> tags if you want.

^^custom_begin^^
 
<h2>Additional Information</h2>
 
<fieldset id="fc_custom_fields">
	<legend>Additional Information</legend>
	<div class="fc_inner">
		<div>
			<h4>Updates</h4>
			<input type="checkbox" name="Update_List" value="yes" checked="checked" />
			<label for="Update_List">Leave this box checked to receive occasional updates about our products. We will not share your email address, and you can unsubscribe at any time.</label>
 
		</div>
		<div>
			<h4>Comments?</h4>
			<p>If you have any comments about your order, or about our checkout process, please let us know.</p>
			<textarea name="Comments" cols="35" rows="6"></textarea>
		</div>
	</div><!-- .fc_inner -->
</fieldset><!-- #fc_custom_fields -->
 
^^custom_end^^

This code will then be inserted in your checkout page, below the address fieldsets and above the shipping fieldset. It will be wrapped in a container div, like this:

<div id="fc_custom_fields_container" class="fc_fieldset_container">
 
<h2>Additional Information</h2>
 
<fieldset id="fc_custom_fields">
	<legend>Additional Information</legend>
	<div class="fc_inner">
		<div>
 
			<h4>Updates</h4>
			<input type="checkbox" name="Update_List" value="yes" checked="checked" />
			<label for="Update_List">Leave this box checked to receive occasional updates about our products. We will not share your email address, and you can unsubscribe at any time.</label>
 
		</div>
		<div>
			<h4>Comments?</h4>
			<p>If you have any comments about your order, or about our checkout process, please let us know.</p>
			<textarea name="Comments" cols="35" rows="6"></textarea>
 
		</div>
	</div><!-- .fc_inner -->
</fieldset><!-- #fc_custom_fields -->
 
</div><!-- #fc_custom_fields_container -->

What to name your fields

You can name your fields anything you want, but we recommend using the underscore (_) for spaces, and capitalizing your input names as you'd like them displayed. For all receipts, we will convert underscores to spaces for you.

For example, if you have <input name=“Update_List” />, it will be displayed in your receipt (and email receipts) as Update List.

What about Receipts and the Datafeeds?

The custom fields will be inserted at the bottom of your your receipt (after checkout), as well as in any emails that include the ^^receipt^^ placeholder.

Custom checkout fields are included in all XML datafeeds from version 0.3.

What if I'm using multiship and I need a custom field per shipto?

No problem! Just wrap your custom fields in ^^multiship_custom_begin^^ and ^^multiship_custom_end^^ and you're good to go.

A Note about Checkboxes

Checkboxes do not post if they are unchecked. This is standard HTML form behavior, but it's worth noting, especially if you're using checkboxes for your XML datafeeds.

Required Fields

With v0.3.1 and on you can required a custom field by adding fc_required to its class (of the input). You can add an error message (which will display if it's left blank) by adding a label.fc_error with for=“your_field_name”, like this:

<label class="fc_error" style="display: none;" for="terms_of_service">Please accept our Terms of Service.</label>

For example, if you wanted to force a Terms of Service acceptance, it'd look like this:

^^custom_begin^^
 
<h2>Additional Information</h2>
 
<fieldset id="fc_custom_fields">
	<legend>Additional Information</legend>
	<div class="fc_inner">
		<div>
			<h4>Terms of Service</h4>
			<input type="checkbox" name="terms_of_service" value="accept" checked="checked" class="fc_required" />
			<label for="terms_of_service">By checking this box you agree to our <a href="http://www.YOURDOMAIN.com/tos">Terms of Service</a>.</label>
			<label class="fc_error" style="display:none;" for="terms_of_service">You must accept our Terms of Service to complete this transaction.</label>
		</div>
		<div>
			<h4>Comments?</h4>
			<p>If you have any comments about your order, or about our checkout process, please let us know.</p>
			<textarea name="Comments" cols="35" rows="6"></textarea>
		</div>
	</div><!-- .fc_inner -->
</fieldset><!-- #fc_custom_fields -->
 
^^custom_end^^

"Sensitive" Custom Checkout Fields

If you'd like to collect information that you do not want to be emailed, such as Social Security Numbers or other sensitive data, you can prefix your field names with h:, like this:

Please enter your Social Security Number: <input type="text" name="h:social_security_number" />

“Sensitive” fields are displayed in the admin's transaction view, and are sent in the XML, but are not emailed.