Custom forms

There are many cases where you need to gather additional data from your customers on your website. This could be as part of an application process, gathering additional details on a product or even within the checkout itself.

These additional bits of information can be collected using StoreConnect’s built in Custom Form feature.

:::note Custom forms are a storefront feature. A register does not show them and does not collect answers to them, so anything you need to capture during an in-person sale has to be collected another way. :::

Form types

There are three types of Form that you can use with StoreConnect:

Generic forms

Think of Generic forms as a way to gather information from a customer and put this into your Salesforce org. This could be an advanced Web to Lead style form, or even a multi step application process that helps determine which product to buy. For a brief introduction to Generic Forms, see our Generic Forms video.

Checkout forms

Checkout Forms are designed to capture information relating to the entire checkout. This could be things like a Purchase Order number, or additional information about the purchaser. They are asked once per checkout and can be asked at any stage of the checkout. You can watch our Checkout Forms video to get an overview on how to use this.

Product forms

The Product Forms feature allows you to get specific information about individual products. They are collected once per product added to the cart. For example, you could ask this to get some text or an image you want to print onto a piece of clothing or perhaps the name and email of a person you are making a donation or purchase on behalf of. Our Product Forms video has a good introduction to how this works.

Using custom forms

Custom Forms gather customer input or session data during specified interaction on your website and push that data to Salesforce. These forms are built by you to collect data based on your own business requirements. Forms can be scoped to one or more stores, allowing reusability or segregation between stores. With Liquid expressions, you can enable dynamic validation and default values, ensuring that forms adapt to your specific requirements.

To create a form, start with the Form object, add one or more questions, then link it to one or more stores. For Product Forms, you must also link your form to any products for which the form is to be used.

This article covers:

• Form Architecture
• Form Configuration
• Rendering Forms

Form architecture

Custom Forms are composed of the following objects:

• Form
• Form Question
• Form Submission
• Form Answer

Form

Defines the form type and the form’s high level configuration.

There are three types of forms:

• Checkout Form - Gathers extra order or customer information during the checkout process.
• Product Form - Collect customers input related to a product when a customer adds that product to the cart.
• Generic Form - Collect data independent to any products or the checkout process and can placed anywhere on the website.

Form question

Contains the metadata for each question, including:

• The question.
• Whether an answer is required.
• Whether the question and its input are hidden from the customer.
• Validation rules.
• Data Type: Text, Text Area, Boolean, Integer, Decimal, Date, Datetime, Picklist, Multi-Picklist, or File. The multi-select option is labeled Picklist (Multi-Select) in the dropdown but stored as Multi-Picklist, which is the value to use in Liquid or through the API.
• Default Value, as a static value or a Liquid expression.
• Picklist Values, required when the data type is Picklist or Multi-Picklist.
• Whether the customer can edit their answer after checkout, from the order page.

Form submission

Completed form submitted by a customer which could be linked to an order or order product.

• Checkout Forms lookup to the order.
• Product Forms lookup to the Order Item.
• Generic Forms don’t lookup to any object but you can insert or request data that can be used to link the form to a Contact or Account, etc.

Where a Product Form is used, if the product is added to the cart multiple times with different answers each time, each unique set of answers creates a new order product. Each unique set of answers creates a separate form submission and each is related to the corresponding order product. This allows you to see what qty of a product relates to what answers.

It is likely you need the answers to be stored in a field on some other object, or perhaps you need to trigger an action depending on the answer given. Either way, you are best to build one or more Flows to manage these as you need.

Form answer

The answer to a question in the form. The Form Answer stores:

• The Form Submission this answer belongs to.
• The original question.
• The provided answer to the question.
• The data type for the answer.

Form configuration

There are many configuration options available. Not all fields require a value so only use the fields you need to achieve the desired outcome.

Form

Record Type

The form record type allows you to choose a form based on its context or purpose, and can be switched between Checkout, Generic, and Product forms.

Form Conditions

A Liquid expression that controls when the form appears during checkout. Write the expression on its own, with no {% ... %} or {{ ... }} wrapper. See Conditions for examples.

Display Mode

Display Mode (s_c__Display_Mode__c) sets where the customer fills in a Product or Checkout form: on the product page, during checkout, or on the order details page after payment.

Display Mode	Product form	Checkout form
Add to Cart (add_to_cart)	The questions appear on the product page. The customer answers them before adding the item to the cart.	Never shown. Do not use this value on a Checkout form.
In Checkout (in_checkout)	The questions appear during checkout, once for each cart line, under the product name.	The questions appear during checkout, once for the whole order.
After Checkout (after_checkout)	The questions appear on the order details page after payment, once for each order line.	The questions appear on the order details page after payment, once for the order.

If you leave Display Mode blank, a Product form works as Add to Cart and a Checkout form as In Checkout. Generic forms ignore the setting.

For example, set Display Mode to After Checkout on a ring’s Product form to collect the engraving text after the order is placed. The customer sees no questions while shopping, and the order details page shows the engraving questions under each ring.

Success Page

This is essentially a lookup for a page, either an existing one you’d like to use or a new one you can create to be used as the success page after the form is submitted.

Form question

Picklist Values

To define multiple values in a picklist, separate each option with a semicolon (;). Each value you specify will appear as a selectable item in the dropdown.

```text

Option 1;Option 2;Option 3 ```

Picklist expressions

Set Picklist Type to Expression to generate the options with Liquid instead of typing them. (Default Type works the same way for the Default Value field.)

When using expressions for picklist options, both label and value must always be specified, even if you are providing static default values.

Example:

```liquid

label: “Select a color;Red;Green;Blue” | split: “;” value: “;red;green;blue” | split: “;” ```

• label: The text shown to users in the picklist.
• value: The actual value submitted when a user selects a label.

For instance, if a user selects “Green”, the submitted value will be “green”.

You can use Liquid variables or collections to populate picklists dynamically.

Example: populating countries

```liquid

label: all_countries | map: “name” value: all_countries | map: “alpha3” ```

• all_countries: A collection of country objects.
• name: The visible name of each country.
• alpha3: The corresponding 3-letter country code (ISO Alpha-3), assuming you wish to submit the 3 char ISO code for the country.

Validation Rule

Validation rules follows this format: {validation message}: {validation condition}

• validation message - The error message shown to the user when the condition fails.
• validation condition - A condition written in Liquid syntax that determines whether the input is valid.
• Use value to refer to the submitted answer.

Example:

This rule enforces that the submitted answer is either “yes” or “no” and provided an error message to make that clear.

```liquid

You must enter ‘yes’ or ‘no’: value == “yes” or value == “no” ```

File Upload

Custom Forms support file uploads by using the File data type in a Form Question. This allows customers to upload documents, images, or other files as part of their form submission.

• The uploaded file will be saved as a URL in the corresponding Custom Form Answer’s URL field.

• File uploads submitted via the custom form are stored in your website’s CDN, and individuals with the direct link can access them.

• No record is created in the Media object that points to the asset in the CDN.

Rendering forms

Checkout forms

Your customers see an In Checkout form on every checkout step that includes a forms snippet. The base theme includes one on all four steps, so a form with no condition appears on each of them:

Checkout step	Snippet
Customer Information	checkout/customer_information/form
Shipping / Delivery Information	checkout/shipping_information/form
Payment Information	checkout/payment_information/additional_info
Accept Terms (Review)	checkout/accept_terms/form

To show a form on one step only, add a condition with current_checkout_step. In a custom checkout theme, leave the snippet out of any step that should not show forms.

Product forms

Where a Product form appears depends on the Display Mode, as described under form configuration:

• Add to Cart: the questions appear on the product page. The answers are saved with the cart line and shown in the cart.
• In Checkout: the questions appear on each checkout step, under the name of the product they belong to. The customer answers once for each cart line.
• After Checkout: the questions appear under each matching line in the order summary on the order details page.

Variants and bundles

Two product structures change where a Product form appears. Check both before you attach a form.

Variants

A form attached to a master product does not reach every place the variants appear. Only the product page falls back to the master.

Display Mode	A form on the master only, for a variant line
Add to Cart	Appears on the variant’s product page
In Checkout	Does not appear
After Checkout	Does not appear

The fallback is all or nothing. A variant that has a form of its own stops inheriting from the master completely, including forms set to a different Display Mode. A variant with its own Add to Cart form does not inherit the master’s After Checkout form.

:::warning An After Checkout form attached only to a master product collects nothing when a customer buys a variant. It does not appear on the product page, which shows Add to Cart questions, and it does not appear on the order, which reads the variant’s own forms. Nothing reports this, so the form still looks correct in Salesforce. :::

To collect the same answers however the customer buys, attach the form to each variant rather than to the master.

Bundles

Attach a form for a bundle to the bundle product itself, not to the products inside it. The customer answers it while configuring the bundle, before the bundle is added to the cart.

The answers are recorded once for the bundle, not repeated against each product the bundle puts in the cart. A bundle that adds four products still stores one set of answers.

A form attached to a product inside a bundle behaves differently depending on its Display Mode:

• Add to Cart questions never appear. The bundle page shows the bundle’s own form only, and the customer never visits the product page of a product inside the bundle.
• In Checkout and After Checkout questions appear as usual, because each product in the bundle becomes its own cart line and then its own order line.

Generic forms

Generic forms can be embedded onto any page of your StoreConnect site using a little Liquid. They can also be added to content blocks the same way.

Example Code Snippet:

```liquid

{% assign custom_form = all_custom_forms[‘a0tAAAAREPLACEAAAA’] %}

{% form ‘custom-form’, identifier: custom_form.id %} {% render ‘custom_forms/questions’, questions: custom_form.questions, form: form %} {% endform %} ```

Replace a0tAAAAREPLACEAAAA with the Salesforce record ID of the form.

Conditions

A Form Condition is a Liquid expression that decides when the form appears. Write the expression on its own, with no {% ... %} or {{ ... }} wrapper.

Use current_checkout_step to pin a checkout form to one step of the checkout. It returns one of customer_information, shipping_information, payment_information, or accept_terms.

Condition	The form appears
current_checkout_step == "customer_information"	Only while the customer is entering their details
current_checkout_step == "shipping_information"	Only on the shipping step
current_checkout_step == "payment_information"	Only on the payment step
current_checkout_step == "accept_terms"	Only on the terms and conditions step

Invert any of these with != to hide the form on that step and show it everywhere else.

Combine expressions to narrow it further:

• On either the shipping or the payment step:

  ```liquid

  current_checkout_step == “shipping_information” or current_checkout_step == “payment_information” ```

• On the payment step, and only for a signed-in customer:

  ```liquid

  current_checkout_step == “payment_information” and (current_customer != nil) ```

• For any signed-in customer, at any step:

  ```liquid

  current_customer != nil ```

Conditions only apply during checkout. They are ignored on the product page and for After Checkout forms. An After Checkout Checkout form is added to every order, and an After Checkout Product form to every order line for that product.

Important notes

Snapshotting

To maintain data integrity, form changes don’t impact existing form submissions, as answers are stored with both the question and its data type.

Hidden and uneditable fields

Check Hidden on a Form Question to capture an answer without showing the question. The field renders as <input type="hidden">, so the customer never sees it, but the value is still submitted and stored as a Form Answer. Pair it with a Default Value to record something the customer does not need to type, such as a campaign code or a value read from the session.

To show a pre-filled value the customer cannot change, use the readonly attribute in a custom question snippet in your theme, not disabled. A browser does not submit a disabled input, so the answer would be lost.

Check Editable on a Form Question to let the customer change their answer after checkout, from the order details page. Questions on an After Checkout form are always editable, whether or not Editable is checked.

In this section

• Collect customer signature at checkout
• Build an application form with payment
• Build an application form with payment - part 2