Custom forms let you collect structured information from customers at key points in their journey — adding a product to cart, progressing through checkout, or after completing an order. All responses sync to Salesforce automatically as FormAnswer and FormSubmission records, linked to the customer's Contact record and the order.
Display modes
Each form has a display mode that determines when and where it appears.
| Mode | When it shows |
|---|---|
| Add to cart | When the customer adds a specific product to their cart |
| In checkout | At a specific step during the checkout flow |
| After checkout | After the order is completed; the customer completes and submits the form post-purchase |
Forms in in_checkout mode can have a Liquid condition that controls at which checkout step the form appears — for example, only on the shipping step, or only when a specific product type is in the cart.
Question types
| Type | Input |
|---|---|
| Text | Single-line text input |
| Text area | Multi-line text input |
| Integer | Whole number |
| Decimal | Number with decimal places |
| Boolean | Yes/No checkbox |
| Date | Date picker |
| Datetime | Date and time picker |
| Picklist | Single-select dropdown |
| Multi-picklist | Multi-select dropdown (answers stored as semicolon-separated values) |
| File | File upload |
Default values
Questions can have default values that pre-fill the field. Default values can be static or evaluated as a Liquid expression at render time.
Examples:
- Today's date:
'now' | date: '%Y-%m-%d' - Store name:
current_store.name - A derived value:
current_store.name | size | plus: 1
Dynamic picklist options
Picklist and multi-picklist questions can generate their option lists from a Liquid expression, allowing options to reflect live store data rather than a fixed list.
Example — populate a picklist with the store's active payment provider names:
label: current_store.payment_providers | pluck: "name"
value: current_store.payment_providers | pluck: "id"
Validation
Questions support Liquid-based validation rules. Each rule is written on its own line in the format Error message: liquid_condition. If the condition evaluates to false, the error is shown and the form cannot be submitted.
Example validation rules:
Terms must be accepted: value == "true"
Please enter a valid email: value contains "@"
Value must be at least 10: value | plus: 0 >= 10
The value variable holds the customer's current answer for that question. Required fields are validated as a separate flag before Liquid rules are applied.
Conditional display
Form-level Liquid conditions control whether the entire form is shown at a given checkout step. Individual questions can also be hidden or shown based on conditions, allowing forms to adapt to the customer's context — for example, showing a business registration question only when the customer's account type is commercial.
Scoping
Product forms — a form is attached to one or more products. It appears when any of those products is added to the cart.
Store forms — a form is attached to one or more stores. It applies to any checkout on those stores, subject to display mode and conditions. A single form can be reused across multiple stores.
Post-checkout answering
Forms with the after_checkout mode create empty, editable answer records when an order is placed. The customer completes the form from their account dashboard after purchase and can update their answers.
This suits:
- Enrolment and registration forms that don't need to block checkout
- Gift message content for gift purchases
- Additional information required for fulfillment that the customer provides at their convenience
When a customer updates an answer, the previous version is marked as stale in Salesforce and the new answer is stored. Both are retained for audit purposes.
Salesforce records
All form responses sync to Salesforce automatically.
FormSubmission — one record per form submission, linked to the Contact, Order, store, and form.
FormAnswer — one record per question answer, linked to its FormSubmission. Fields include: the answer value, the question text as rendered at the time of submission, the question data type, a sensitivity flag for PII classification, an editable flag, a file URL for file upload questions, and a stale flag when the customer has updated their answer.
All records are standard Salesforce objects, reportable with SOQL and available in Salesforce reports and dashboards.
Form identifiers and Liquid embedding
Each form has a unique identifier. Forms can be embedded in CMS pages and theme templates using the custom-form Liquid tag, referenced by identifier. This allows forms to appear anywhere on the storefront — not only at product or checkout entry points.